Troubleshooting Agents

Overview

This guide covers the most common issues encountered when installing, configuring, or running a Brainfish agent.

---

Widget not loading

Symptoms: The Brainfish widget button does not appear on the page.

Likely causes:

• The widget script is blocked by a Content Security Policy (CSP).
• The widgetKey passed to Brainfish.Widgets.init() is incorrect or missing.
• An ad blocker or browser extension is blocking the CDN request.

Steps to resolve:

1. Open browser DevTools and check the Console and Network tabs for errors.
2. Search the Network tab for web.js. If blocked, a CSP error will appear in Console.
3. Add the required Brainfish domains to your CSP frame-src and connect-src directives:
   • frame-src: https://app.brainfi.sh https://agent.brainfi.sh
   • connect-src: wss://analytic.brainfi.sh
4. Confirm the widgetKey starts with bf_agent_ and matches the key in your Brainfish dashboard.
5. Temporarily disable browser extensions to rule out ad blockers.

---

Agent returns low-confidence or incorrect answers

Symptoms: The agent frequently says it does not know the answer, shows low confidence, or gives wrong answers.

Likely causes:

• The knowledge base does not cover the topic being asked.
• Articles are too short, image-heavy, or lack clear headings.
• The agent is searching the wrong knowledge source.
• Custom instructions are too restrictive.

Steps to resolve:

1. Run a Simulation with the failing questions to see confidence scores and citations. See Simulation: Test Your Agent.
2. Check citations in simulation results to confirm the agent is finding the right articles.
3. Review the knowledge source connected to the agent in Agent Settings > Knowledge Settings.
4. Improve article quality: add clear headings, use plain language, and ensure each article covers one topic fully.
5. If custom instructions include restrictive phrases like "only answer about X", check whether they block valid answers.

---

Handoff button does nothing

Symptoms: The user clicks a handoff button but nothing happens.

Likely causes:

• The third-party chat SDK has not finished loading.
• The callback function contains a syntax error.

Steps to resolve:

1. Open DevTools Console and click the button. Look for JavaScript errors.
2. Check whether the third-party SDK is loaded by typing typeof window.Intercom or typeof window.zE in Console. It should return 'function', not 'undefined'.
3. Add a guard at the top of your callback:

if (typeof window.Intercom !== 'function') {
  console.warn('Intercom not loaded');
  return;
}

4. Confirm window?.Brainfish?.HelpWidget?.close('brainfish-trigger-button') is called to close the Brainfish widget before opening the support chat.

---

Widget events are not firing

Symptoms: Event listeners for onBrainfishHelpWidgetOpened, onBrainfishHelpWidgetClosed, or similar events are not triggering.

Likely causes:

• The event listener is registered before the widget initialises.
• The event name has a typo (event names are case-sensitive).
• The AbortController was aborted before the event fired.

Steps to resolve:

1. Check the exact event names in the events matrix in Configuring Self Serve Agents.
2. Register your listener after the widget initialises, or wait for the onBrainfishReady event first.
3. Verify your AbortController has not already been aborted.

---

User identity is not being tracked

Symptoms: Sessions in Analytics show as anonymous even though Brainfish.Widgets.identify() is being called.

Likely causes:

• identify() is called before init() completes.
• The userId field is undefined.
• A Do Not Track (DNT) setting is active for the session.

Steps to resolve:

1. Ensure identify() is called after init(). Wait for the onBrainfishReady event if using async loading.
2. Log userId to confirm it is not undefined at call time.
3. Check whether window.BrainfishAnalytics('isTrackingDisabled') returns true.

---

Region segmentation is not applying

Symptoms: Users from a specific region see the wrong agent or no agent.

Steps to resolve:

1. Review Configuring Region Segmentation for the correct override syntax.
2. Log the widgetKey and overrides values being passed to init() to confirm they match expectations.
3. Confirm the correct agent is published and active in the Brainfish dashboard.

---

Still stuck?

Contact Brainfish support with the following:

• The URL where the issue occurs
• Your widget key (the bf_agent_... string)
• A screenshot of the browser Console at the time of the issue
• Your browser and OS version
• Whether the issue reproduces in a private or incognito window