Troubleshooting

Solutions to common problems when embedding the Navigic widget.

Check the script tag is loaded. Open the browser console and look for network errors. The script URL should be https://releases.navigic.ai/embed/embed.js?v=7.

Check your API key. The data-api-key attribute must start with pk_wk_. If you see 401 errors in the console, the key is invalid or has been revoked.

Check for JavaScript errors. Other scripts on the page may throw before the widget loads. Look for errors in the console that appear before the widget script runs.

Check for CSS conflicts. If the widget renders but is invisible, another stylesheet may be setting display: none or visibility: hidden on the widget's container. Inspect the widget element in DevTools.

"Disconnected" Status

The widget shows "disconnected" when it can't reach the runtime gateway.

Check your network. The widget connects to https://navigic.ai/dashboard/runtime via WebSocket. Corporate firewalls or proxies may block WebSocket connections.

Check that an agent is deployed. Go to Studio in your dashboard and verify an agent is live. The widget connects but won't respond without a deployed agent.

Check gatewayUrl if using the JavaScript API. When calling NavigicWidget.init() programmatically, make sure gatewayUrl is set to https://navigic.ai/dashboard/runtime.

NavigicWidget.init({
  workspaceId: "pk_wk_YOUR_KEY",
  gatewayUrl: "https://navigic.ai/dashboard/runtime",
});

Origin Not Allowed

If the console shows a CORS or origin error, your domain isn't in the embed key's allowed origins list.

Go to Settings > Embed in your dashboard
Click on your embed key
Add your domain (e.g., https://yoursite.com)
For local development, add http://localhost:3000 (or whatever port you use)

Origins must match exactly — http:// and https:// are different, and subdomains like www. must be listed separately.

This means the widget connects successfully but the agent isn't generating replies.

Check your agent deployment. Go to Studio in the dashboard. Make sure an agent is deployed and its status is "Live".

Check the conversation in the dashboard. Go to your workspace conversations. If messages appear there but not in the widget, there may be a rendering issue — check the browser console for errors.

Identity Verification Fails

If identify() doesn't link the conversation to your user:

Check the HMAC hash. The hash must be computed using your secret key (starts with sk_wk_), not your publishable key. See Identity Verification.

Check that the user ID matches. The userId passed to identify() must exactly match the string used to compute the HMAC.

Check the hash is hex-encoded. The HMAC output must be a lowercase hex string (64 characters for SHA-256).

// Correct
NavigicWidget.identify("user_123", {}, { userHash: "a1b2c3..." });
 
// Wrong — don't pass the raw bytes
NavigicWidget.identify("user_123", {}, { userHash: Buffer.from(...) });

Inline Mode Shows Nothing

When using data-display-mode="inline":

Check the container element exists. The data-target-element selector must match an element already in the DOM when the script loads.

<!-- Container must come BEFORE the script -->
<div id="navigic-chat" style="height: 600px;"></div>
 
<script
  src="https://releases.navigic.ai/embed/embed.js?v=7"
  data-api-key="pk_wk_YOUR_KEY"
  data-display-mode="inline"
  data-target-element="#navigic-chat"
  async
></script>

Check the container has a height. The widget fills 100% of its container. If the container has zero height, the widget will be invisible.

Mobile Layout Issues

Bubble mode automatically switches to full-screen on viewports under 480px. If this conflicts with your mobile layout, consider using inline mode where you control the sizing via CSS.

Panel mode uses full-width with a backdrop overlay on viewports under 640px. This is intentional — there isn't enough space for a sidebar panel on small screens.

Still Stuck?

Open the browser console and look for errors prefixed with [Navigic]. These provide specific diagnostic information about connection issues, configuration problems, and runtime errors.

title: Troubleshooting description: Common issues when embedding the Navigic widget and how to fix them. order: 6