---
title: "Troubleshooting Agents"
description: "Overview"
canonical_url: "https://help.brainfi.sh/articles/troubleshooting-agents-Q1L7AYfrTm"
md_url: "https://help.brainfi.sh/articles/troubleshooting-agents-Q1L7AYfrTm.md"
---
# 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](/articles/simulation-test-your-agent-1TD46giCEY).
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:

```javascript
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](/articles/configuring-self-serve-agents-5xYwkkwa4S).
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](/articles/configuring-region-segmentation-for-self-service-agents-a5FxDPHxFi) 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