Ai Copilots Troubleshooting

Symptom: "AI summary failed: …" / "AI agent failed: …" on a lead

Cause: The Gemini call itself errored — usually a missing/invalid API key, quota exhaustion, or a model name issue.

Fix: Check the AI configuration (GEMINI_MODEL env override wins over workspace settings) and API key in Settings → Integrations, then retry.

Symptom: "A valid lead id is required for AI processing"

Cause: The client sent lead data without a usable id, so server-side read access couldn't be verified.

Fix: Reload the lead page so the request carries the current record id, then retry the summary or agent action.

Symptom: "AI did not return JSON" — outreach email looks like template filler

Cause: The model reply wasn't parseable subject/body JSON, so the system silently fell back to the deterministic template draft (source shows fallback).

Fix: Retry the draft; if it keeps failing, shorten the record context or verify the agent model is available.

Symptom: "A skill with that name already exists" when saving a copilot skill

Cause: Skill names are unique case-insensitively across the workspace.

Fix: Rename the new skill or update the existing one instead of creating a duplicate.

Symptom: MCP server shows "unavailable" with an error

Cause: The live tools/list probe to the server URL timed out or failed auth.

Fix: Verify the URL is reachable, headers are correct (re-enter them — saved values are encrypted), and the server is enabled; status refreshes on next probe.

Symptom: Copilot panel missing entirely

Cause: The generic copilot requires read access on the settings module; without it the surface doesn't render.

Fix: Ask a System Manager to grant settings read.

Was this helpful?

YesNo