Troubleshooting

Quick fixes for the most common issues. Search this page (Ctrl/Cmd+F) for keywords from your error message — most problems are documented below. If your problem isn't here, email support@coffield.io with:

  1. What you were trying to do
  2. What you expected to happen
  3. What actually happened (a screenshot helps)
  4. Roughly what time it happened (so we can find it in our logs)

Quick links: Widget not appearing · Leads not arriving · Wrong agent answer · HubSpot disconnected · Webhook failures · Sign-in problems

I can't sign in

  • Double-check the email address — it's the one you got the invite at.
  • Use Forgot password? to reset.
  • If you're using a workspace SSO (Google, Microsoft), make sure you're signed into the right account in another tab first.
  • If you have 2FA on, the code window is 30 seconds. If your phone's clock is off, codes will fail — sync the phone's clock.
  • If you keep being kicked back to the login screen after entering the right credentials, your browser is probably blocking session cookies. Allow third-party cookies for coffield.io, or try an incognito window.

The "New agent" button is missing

You've hit your plan's agent limit. See the subheading on the Agents page for the exact number. Either:

  • Delete an agent you no longer use, or
  • Upgrade your plan from Account → Subscriptions.

See 2. Your AI agents for the per-plan limits.

My HubSpot integration disappeared

Most likely you (or someone else on your account) clicked Disconnect. Reconnect from AI Agents → External integrations → HubSpot CRM → Connect HubSpot. Past contacts/notes/deals stay in HubSpot.

I'm at HubSpot Pro plan but I don't see the Connect button

The HubSpot integration is hidden when the platform owner hasn't configured the HubSpot client credentials yet. If you're self-hosting Coffield.io, set HUBSPOT_CLIENT_ID and HUBSPOT_CLIENT_SECRET in your .env file and run php artisan config:clear. On the hosted version, this is configured for you — if it's still hidden, email support@coffield.io.

A visitor said the agent gave a wrong answer

  1. Open AI Agents → Conversations and find the conversation.
  2. Look at what was asked and what the agent said.
  3. Check AI Agents → Knowledge gaps — the agent flags answers it wasn't confident about.
  4. Add the right answer to your knowledge base (see 3. Teaching your agent).
  5. Test again with AI Agents → Agents → Edit → Test.

My agent says "I don't know" too often

That's the agent doing exactly what we told it: refuse to invent answers, and admit when it's outside the knowledge base.

  • Open AI Agents → Knowledge gaps for a list of questions visitors actually asked that the agent couldn't answer confidently.
  • Add focused FAQ entries that cover those questions (paste-text knowledge items work well).
  • For the agent to use the new knowledge, the embed must finish (usually within a minute of save).

Don't loosen the prompt. The temptation is to edit the system prompt to "answer everything you can". Don't — you'll get hallucinations. The right fix is always more knowledge, not less rigour.

Widget not appearing on my website (deep dive)

This is the #1 install issue. Walk through these checks in order; stop when you find the cause.

Step 1 — view the page source

In your browser, open the customer-facing page where the widget should appear. Right-click → View page source (or Ctrl/Cmd+U). Search the source for coffield.

  • You see the script tag → continue to Step 2.
  • You don't see the script tag → the script isn't being injected by your CMS. The most common causes:
    • Squarespace: The script lives in a Code Block that's toggled off. Open the Code Block in the editor and confirm "Display source" is on.
    • Wix: Custom HTML embeds need to be published. Save the page, then click Publish.
    • WordPress: The plugin or theme that injects raw HTML may be sanitising the <script> tag. Try the WPCode or Insert Headers and Footers plugin instead.
    • Webflow: Custom code lives at site-level under Project Settings → Custom Code → Footer Code. Republish the site after pasting.
    • Shopify: Theme code editor → theme.liquid → paste before </body> → Save.

Step 2 — open the browser console

Right-click → Inspect → Console tab. Reload the page.

Message you see What it means Fix
Refused to load the script … because it violates the following Content Security Policy directive: "script-src …" Your site's CSP is blocking us. Add https://coffield.io (or your custom domain if you white-label) to your script-src and connect-src directives.
Refused to connect to '…' because it violates the following Content Security Policy directive: "connect-src …" CSP is letting the script load but blocking the XHR / fetch calls it makes. Same fix — add the host to connect-src.
Failed to load resource: the server responded with a status of 404 for /agent.js Wrong host in your snippet. Confirm the snippet uses the host your account manager gave you. White-label customers use their custom domain.
Failed to load resource: net::ERR_BLOCKED_BY_CLIENT An ad-blocker on the visitor's machine is blocking the script. Test in a fresh incognito window without extensions. The widget will load for non-blocked visitors.
Coffield.io Embed: agent unavailable (HTTP 401) Install key invalid (typo or revoked). Confirm the snippet's data-install-key="…" matches what's shown in Edit agent → Show install snippet.
Coffield.io Embed: agent unavailable (HTTP 403) The agent is set to draft or has been disabled. Open the agent's edit page and confirm Status is Active.
Coffield.io Embed: agent unavailable (HTTP 404) Install key doesn't match any agent. Double-check the snippet was copied correctly; the key is case-sensitive.
Console is empty but widget bubble doesn't appear Visual conflict — see Step 3.

Step 3 — check for visual conflicts

If the script loads cleanly but you can't see the chat bubble:

  • Z-index war. Some themes have a sticky footer with a high z-index. The bubble defaults to z-index: 9999; if your theme uses higher, override the bubble's z-index via custom CSS (or use the white-label launcher_z_index setting on Pro+).
  • Iframe sandbox. If your site is itself loaded inside an <iframe> (e.g. preview mode in some CMS editors), the bubble may not appear. Test on the published site, not the preview.
  • Mobile-only theme breakpoint. A few themes hide everything below a certain breakpoint. Resize the window or test on a real phone.
  • Custom CSS hiding it. Search your site's CSS for .coffield-launcher, coffield-widget, or any rule that sets display: none on third-party elements.

Step 4 — confirm with curl

If you have shell access, run:

curl -I https://coffield.io/agent.js

You should see HTTP/2 200 and an X-Agent-Embed-Version: … header. If you don't, the platform itself is having a moment — check our status page or email support.

Step 5 — last-resort reinstall

  1. Edit the agent.
  2. Click Show install snippet at the top of the form.
  3. Click the copy button.
  4. Paste it into the customer-facing page, replacing the existing snippet (don't paste alongside it — duplicate snippets confuse things).
  5. Save / republish.
  6. Hard-reload the customer page (Ctrl/Cmd+Shift+R).

Leads aren't appearing in the dashboard

  1. Confirm capture is on. Open Edit agent → Capture leads → Collect leads from this agent — must be ON.
  2. Confirm the form has at least one contact channel. Look for the green/red banner under the form. If it's red, the server is rejecting every submission until you add at least one of name / email / phone. See § 4.1.
  3. Confirm the visitor finished the form. Open AI Agents → Conversations for the visitor's session. If you see lead-form prompts but no submission, they bailed out — the lead isn't lost; it's not a lead.
  4. Wait one minute. Lead persistence is queued for reliability — there's a 5–30 second lag between submit and appearance.
  5. Check capability gating. Some operator-facing single-field switches (lead capture, support triage) are tier-gated. On Starter you have lead capture but not support triage. Open External integrations → Capability modules to see what's enabled.
  6. Still nothing. Email support@coffield.io with the conversation ID from step 3 — we can trace the request through the logs.

My website embed isn't loading

See the Widget not appearing on my website (deep dive) section above. The 5-step checklist covers 90% of cases.

Webhooks are failing

Open External integrations → Webhook Deliveries to see the failed attempts with their HTTP status and response body.

HTTP status / error Likely cause Fix
401 from your receiver HMAC verification failed on your side. Make sure you're using the same signing secret that's shown in Webhook Endpoints → Edit. The signature is HMAC-SHA256(body, secret) in the X-Coffield-Signature header.
404 / 410 URL is wrong or the receiver was removed. Update the endpoint URL or delete the webhook.
5xx Receiver had an outage. We retry with exponential backoff (5 attempts over ~6 minutes). If it stays 5xx, the deliveries land in Failed.
Connection refused / Timeout Receiver's host is unreachable. Check the host is publicly accessible. We do not deliver to private IP ranges (SSRF guard).
Refused — endpoint URL is on a private IP range You configured a 127.x.x.x / 10.x.x.x / 192.168.x.x URL. Use a public URL or a tunnel (ngrok, cloudflared) during development.
Refused — http:// is not allowed Plain HTTP is rejected by default. Use https://. If you must test against http:// in development, set AGENT_WEBHOOK_ALLOW_HTTP=true (self-hosted only).

See 9. Outbound webhooks for the full delivery payload schema and signature recipe.

REST API requests fail

Symptom Fix
401 Unauthorized The token in Authorization: Bearer … is wrong, expired, or for a different workspace. Generate a new one under External integrations → API tokens.
403 Forbidden Your plan tier doesn't include API access. Upgrade to Pro+.
429 Too Many Requests You're past the per-token rate limit (default 600/min). Back off and retry after the Retry-After header.
404 on a known agent ID The agent belongs to a different workspace. Tokens are tenant-scoped; you can only see what your workspace owns.
Empty response body but 200 The endpoint exists but the result set is genuinely empty (e.g. no leads in the date range you queried).

See 10. REST API for the full endpoint catalog.

MCP token authentication fails

Symptom Fix
401 Unauthorized from the MCP server Token is wrong or revoked. Regenerate from External integrations → MCP tokens → New token.
403 capability_disabled The capability the tool needs (Scheduling, Knowledge, etc.) isn't enabled for your plan tier.
429 Too Many Requests Per-token burst throttle tripped. Wait and retry. Tokens are also subject to brute-force lockout — if you fail 10+ times in a minute, the IP is locked out for 15 minutes.

See 15. External integrations for the token model and per-tier limits.

"Page not found" errors

If you bookmarked a deep link and the page is gone (deleted lead, deleted agent, etc.), use the sidebar to navigate to the parent section. We don't share data across workspaces, so bookmarks from one workspace won't open in another.

If the whole dashboard 404s after sign-in, your session is bound to a workspace that was deleted. Sign out and sign back in — you'll be reseated in the next workspace you belong to.

A teammate can't see something I can see

Permissions are role-based (Spatie). Open Team Management → Members → Edit member and check:

  • Their role (Owner, Manager, Member, Viewer).
  • The specific permission for the feature (e.g. Manage agents, View leads, Manage integrations).

If they should see it but the role is right, sign them out and back in — Filament caches the role at sign-in.

My voice recording got rejected

Reason Fix
File too large Limit is 50 MB per upload. Compress to MP3 / Opus first.
Format not supported We accept .mp3, .m4a, .wav, .ogg, .opus. Re-encode if you have a different format.
Quota exhausted Voice recording is metered per month per tier. Check AI Agents → Voice Recordings for your remaining quota. Resets on your billing date.
PII detection failed safe If our scrubber can't run for any reason, we reject the upload rather than store unscrubbed PII. Email support if it persists.

See 14. Voice recording.

My PDF didn't ingest

Symptom Fix
"PDF format not supported" The file is image-only with no text layer and OCR couldn't extract anything readable. Re-export the PDF from the original source (Word, Pages, etc.) or run it through OCR yourself first.
"Quota exhausted" PDF ingestion is metered per month per tier. Resets on your billing date.
Stuck on "Processing" for >10 minutes Email support@coffield.io with the document ID — we can re-queue.

See 3. Teaching your agent.

Still stuck?

support@coffield.io — most replies within one business day. Include:

  • Workspace name (top-left of the sidebar).
  • The exact URL of the page where the problem happened.
  • A screenshot.
  • Browser console output if it's a widget / front-end issue.

For urgent issues on Pro+ accounts, mark the email subject URGENT — <workspace> and we'll prioritise.

Last updated
Need more help? Email support@coffield.io

Your experience on this site will be improved by allowing cookies.