> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpalive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot a HelpAlive install: silent failures and fixes

> The ways a HelpAlive install fails without an error on the page, how to spot each one, how to fix it, and how to reach support.

A silent failure is a HelpAlive install problem that shows no error on the page. This page helps developers find out why HelpAlive isn't working in their app. Most failures are silent, so each entry says how to spot it.

## Troubleshooting at a glance

* **Settings → Setup & API Key** checks your install again when you return. The first step without a check points to the cause.
* `data-debug` on the HelpAlive tag logs what HelpAlive does, and why it refused a call, to the browser console.
* The agent appears only for identified users, and only once it is switched on in **Controls** with a published source.
* `reset()` belongs in your logout code, apart from `identify()`.
* Your project key is public, so you can include it when you email support. Never send your signing secret.

## Prerequisites

* Access to your app in a browser with developer tools.
* Access to **Settings → Setup & API Key** in the dashboard.

## How to find the cause

<Steps>
  <Step title="Read the setup steps">
    Use your app, then come back to **Settings → Setup & API Key**; it checks again when you return. The first step without a check points to the cause. Each step has one line saying what HelpAlive saw.
  </Step>

  <Step title="Turn on console logs">
    Add `data-debug` to the HelpAlive tag while you test:

    ```html theme={null}
    <script src="https://cdn.helpalive.com/sdk/helpalive.js" data-api-key="YOUR_PROJECT_KEY" data-debug async></script>
    ```

    HelpAlive then logs what it does, and why it refused a call, to the browser console. Some lines are at the verbose level, so show all levels in the console. Remove `data-debug` before you ship.
  </Step>

  <Step title="Find your failure below">
    Match what you see to one of the entries below, in order.
  </Step>
</Steps>

## Why does nothing start?

Nothing starts when the HelpAlive tag has no `data-api-key`.

**What you see:** step **Add HelpAlive to your app** still says "Not on your pages yet.", and the console shows nothing, even with `data-debug`.

**Fix:** add `data-api-key="YOUR_PROJECT_KEY"` to the tag, with the key from **Settings → Setup & API Key**. If you regenerated the key, put the new one in the tag, because the old one stops working shortly after.

## Why is the script blocked?

The script is blocked when your Content Security Policy lacks our sources or your nonce, or when an ad blocker or privacy extension blocks it.

**What you see:** step **Add HelpAlive to your app** still says "Not on your pages yet." The console shows an error naming `helpalive.js`, `Content Security Policy` or a blocked request.

**Fix:** add our sources to your policy, and put your nonce on our tag if your policy uses one. See [Content Security Policy](/sdk/csp). Ad blockers and privacy extensions can also block the script: test in a private window with extensions off.

## Why does setup stay on Waiting for someone to sign in?

Setup stays there when `identify()` is never called. The agent never appears either, because it appears only for identified users.

**What you see:** step **Add HelpAlive to your app** says "On your pages. Waiting for someone to sign in to your app." No chat button appears.

**Fix:** call `identify()` after login and on every page load while the user is signed in, with the four queue lines above it. See [Identify users](/sdk/identify).

## Why is identify() refused?

`identify()` is refused when `userId` is empty, or when `userId` or `tenantId` isn't text or a number of up to 255 characters.

**What you see:** the same as above, although your code calls `identify()`. With `data-debug`, the console says why.

**Fix:** pass `userId` and `tenantId` as text or a number, up to 255 characters each. Don't pass an empty `userId`. With a user token, keep the ids in it under 200 characters. Other fields of the wrong type are left out without stopping the call.

## What if reset() runs straight after identify()?

Running `reset()` straight after `identify()` forgets the user at once, which is why the chat button doesn't appear, or doesn't stay.

**What you see:** the chat button doesn't appear, or doesn't stay, although your code calls `identify()`.

**Fix:** move `reset()` into your logout code, apart from `identify()`.

## What if the agent is off, or has no published docs?

Your users don't see the agent until it is switched on in **Controls**, and it can't be switched on until a source is published on **Train**.

**What you see:** step 1 has a check, but **Train the agent on your product** doesn't, or your users don't see the agent. No chat button appears.

**Fix:** publish at least one source on **Train**, then switch the agent on in **Controls**. Check that **Who gets it** includes the user you test with.

## Why does the agent appear only after a short wait?

**What you see:** you switched the agent on, or changed **Who gets it**, but a page that was already open doesn't show the change.

A user who already had your app open sees the change within a minute or a few page loads. Switching the agent off takes effect the same way. A browser that has never loaded the agent's settings gets them at once.

**Fix:** wait a minute, then load a couple of pages.

## Why are requests refused once Only allow verified users is on?

**Only allow verified users** means that HelpAlive refuses every request without a valid user token.

**What you see:** the chat button appears, but asking something shows "Your session needs a refresh. Reload the page to keep chatting." Users without a token also stop showing in **Reports** and **Audience**.

**Fix:** send a token from every page that calls `identify()`, or turn the switch off while you fix it. See [Verify users](/sdk/verify-users).

## What if your account has no subscription?

The agent shows only during your free trial or while you are subscribed.

**What you see:** everything is set up, but the chat button never appears.

**Fix:** subscribe on **Settings → Billing and usage**.

## Why does the agent stop offering assists?

The agent stops offering assists because a usage limit was reached: your plan's, or one you set per user, tenant or organization on **Controls**. Users are never told about a limit.

**What you see:** the agent answers in words and no longer offers to do tasks. Later it may say "Chat isn't available right now. Please try again later."

**Fix:** see [Limits and usage](/dashboard/usage).

## Check it works

When the first three steps on **Settings → Setup & API Key** have a check, **Everything is working.** shows at the top. Sign in to your app as a user who gets the agent, open the chat button, and ask a question your docs answer.

## Still stuck?

Email [support@helpalive.com](mailto:support@helpalive.com). To help us answer quickly, include:

* the address of a page where the problem happens, and the browser you used;
* which steps on **Settings → Setup & API Key** have a check, and what step 1's line says;
* what the browser console shows with `data-debug` on the tag.

Your project key is public, so you can include it. Never send your signing secret.

## Next

<CardGroup cols={3}>
  <Card title="Install the script" icon="code" href="/installation">
    Every rule of the install.
  </Card>

  <Card title="Controls" icon="sliders-horizontal" href="/dashboard/controls">
    Switch the agent on and choose who gets it.
  </Card>

  <Card title="Content Security Policy" icon="shield" href="/sdk/csp">
    The sources to allow.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.