# Debug the widget on your site

> Turn on the widget's console log, send it to your error tracker, and check which version runs.

When the widget doesn't do what you expect, its own log usually says why. By default it writes only warnings and errors to the browser console.

## Turn on more detail

| Level | What the console shows |
| --- | --- |
| `off` | Nothing |
| `error` | Errors |
| `warn` | Errors and warnings. The default |
| `info` | Also the main steps, such as opening and connecting |
| `debug` | Also the details of each step |
| `trace` | Everything, down to each piece of a streamed reply |

- **For one page load,** add `?helpai-debug=debug` to the page's address (`&helpai-debug=debug` if it already has a `?`).
- **Across reloads,** run `HelpAI.setDebug('debug')` in the console once the widget has loaded. This browser remembers it until you run `HelpAI.setDebug(false)`. With the NPM package it's `chat.setDebug('debug')`.

The address wins over a remembered level. `HelpAI.debugLevel()` shows the current one.

Debug and trace lines use the console's debug level. In Chrome, show **Verbose** messages to see them.

## Send the log to your error tracker

```html
<script>
  window.HelpAI = window.HelpAI || function () { (HelpAI.q = HelpAI.q || []).push(arguments); };

  HelpAI('onLog', (entry) => {
    // entry is { level, scope, message, payload }
    if (entry.level === 'error' || entry.level === 'warn') {
      myErrorTracker.log(entry.level, 'help.ai: ' + entry.message, entry.payload);
    }
  });
</script>
```

`myErrorTracker` stands for your own tool, such as Sentry or Datadog. Put this before the widget's script to catch its first lines too. Only lines that pass the current level reach it, and `HelpAI('onLog', null)` stops it.

To react to failures in your own code, listen for the `error` event: `chat.on('error', (error) => …)`.

## Check which version runs

Type `HelpAI.version` in the console. It shows the widget's version, such as `1.11.0`.

## Common problems

| What you see | What to do |
| --- | --- |
| `HelpAI is not defined` | Your code runs before the widget's script. Add the line from [Control the widget with JavaScript](https://docs.help.ai/customize-and-extend-the-widget/control-the-widget-with-javascript) that holds calls until it loads |
| `HelpAI.ready()` never resolves | You installed the `<web-ai-chat>` element, which the `HelpAI` global doesn't control. Use the element's own `ready` |
| Requests fail with 401 `USER_TOKEN_INVALID` | The sign-in token was turned down. See [Verify signed-in users](https://docs.help.ai/customize-and-extend-the-widget/verify-signed-in-users) |
| A `data-helpai-*` button does nothing | The attributes drive only the first widget on the page, and not a deployment set to **Embed in an iframe** |
| No chat bubble | Check that the deployment is **Live** and that your site is in its **Allowed websites**. See [Add the chat widget to your website](https://support.help.ai/deployments-and-the-widget/add-the-chat-widget-to-your-website) |

<Tip>
Asking a customer to reproduce a problem? Have them add `?helpai-debug=trace` to the page's address and send you the console output.
</Tip>