Common Errors

Things that go wrong, and how to fix them.

Widget doesn't appear

1. Wrong slug. Double-check the slug from dashboard → Settings → Embed. Slugs are case-sensitive.

2. Restricted agent without token. If your agent is in restricted mode (Settings → Access), you must pass token. Public agents work without it.

3. CSP blocking the widget iframe. If you have a strict Content Security Policy, you need to allow:

script-src https://unpkg.com https://agents.bitpalm.ai
frame-src https://agents.bitpalm.ai
connect-src https://agents.bitpalm.ai

4. Ad blocker. Some aggressive blockers flag chatbot domains. Test in an incognito window without extensions.

"Failed to load resource: 401" in console

The agent is restricted and your token is missing or invalid. Check data-token / token matches the dashboard.

Widget appears but messages don't send

1. Network errors in DevTools → Network tab. Look for failing requests to agents.bitpalm.ai/api/chat. Common causes: CSP blocking connect-src, corporate proxy, slow network.

2. Agent is paused. Check dashboard → your agent has a status indicator. If it shows paused, click resume.

3. Plan limits reached. If you've hit your monthly message limit, the bot stops responding. Check dashboard → Billing.

Identify doesn't work

1. Calling before widget initializes. Make sure widget exists before calling identify(). With React, dispatch a bitpalm-identify event after mount.

2. Wrong slug in event detail. The slug in CustomEvent.detail must match your widget's slug.

3. Visitor opted out. If localStorage._bp_optout === "1", identify is silently dropped.

Auto-identify catches the wrong fields

Add data-bp-identify="off" to forms that shouldn't be captured (admin forms, delete-account forms). For false positives on generic forms, use explicit data-bp-* markers to control which fields map to what. See Form Hints.

Widget covered by other elements

Increase the z-index:

createWidget({ slug: "...", zIndex: 100000 });

Or via script tag: data-z-index="100000".

"Cannot read properties of undefined" errors

Usually means you're calling widget.method() on an undefined variable. Common causes:

// ❌ Wrong — runs before page loads
const widget = createWidget({ slug: "..." });
widget.identify({ ... });  // widget might not be ready yet
 
// ✅ Right — wait for DOM
window.addEventListener("DOMContentLoaded", () => {
  const widget = createWidget({ slug: "..." });
  widget.identify({ ... });
});

Widget reloads on every page navigation

You're rendering <BitPalmAgent /> per-page instead of in the root layout. Move it to your root layout (Next.js: app/layout.tsx) so it persists across navigations.

SPA route changes don't track

The SDK auto-detects pushState / replaceState. If your framework uses something exotic (custom history implementation), file an issue at github.com/BitPalm-LLC/ai-agent-platform.

Can't find error in this list

Email us with:

  • Your agent slug
  • The error message and a screenshot of the browser console
  • Your framework / setup (React + Next.js / Webflow / etc.)
  • Steps to reproduce

We usually respond within a business day.