# Achla AI — documentation for AI agents

> How to install the Achla AI search widget on a website, verify it, and diagnose problems by their AISX-… codes. Full text: https://achlaai.com/llms-full.txt

- Install: https://achlaai.com/en/docs/install (Markdown: https://achlaai.com/docs/install.md)
- Troubleshooting: https://achlaai.com/en/docs/troubleshooting (Markdown: https://achlaai.com/docs/troubleshooting.md)

---

# Install Achla AI on a website

> How to add the Achla AI search widget to a website (HTML, WordPress, Drupal, single-page apps), choose a placement mode, and verify the installation.

HTML: https://achlaai.com/en/docs/install · Markdown: https://achlaai.com/docs/install.md

<a id="quick-answer"></a>
## Short answer for AI agents

- **What:** one `<script>` tag with the site's public key: `<script src="https://achlaai.com/w.js" data-key="YOUR_PUBLIC_KEY" defer></script>`. The real key (starts with `pk_`) is in the Achla AI dashboard under **Settings → Embed code**.
- **Where:** in the HTML of every page that should have search, just before `</body>`, exactly once per page.
- **WordPress / Drupal:** prefer the official plugin ([WordPress.org](https://wordpress.org/plugins/achlaai/), [Drupal.org](https://www.drupal.org/project/achlaai_search)) over pasting the tag.
- **Inline mode** needs `<div id="ai-search"></div>` on the page; **attach mode** needs a CSS selector of an existing search `<input>`. Default (bubble) needs nothing else.
- **Verify:** `curl -s "https://achlaai.com/api/widget-config?key=YOUR_PUBLIC_KEY"` must return `"enabled":true`; the browser console must show no `[ai-search]` lines; a test question must return an answer with sources.
- **Always finish by verifying** — see [Verify the installation](#verify).
- **Something wrong:** every console message starts with `[ai-search] AISX-…` — look the code up in [Troubleshooting](https://achlaai.com/en/docs/troubleshooting) ([Markdown](https://achlaai.com/docs/troubleshooting.md)).

<a id="prerequisites"></a>
## Prerequisites

The widget shows itself only after the server explicitly enables it for the key. That requires all of the following, set up in the dashboard:

- An account with Achla AI, with the site registered.
- Site ownership verified (via the widget tag or a CMS plugin connection).
- An active plan (paid subscription or the Free plan).
- The first indexing of the site finished — **Overview** in the dashboard shows the status.

Check from any terminal (no login needed — the key is public):

```bash
curl -s "https://achlaai.com/api/widget-config?key=YOUR_PUBLIC_KEY"
```

- `{"enabled":true,"config":{…}}` — ready; the widget will appear wherever the tag is installed.
- `{"enabled":false}` — key unknown or replaced, project not active, index not ready, or ownership/plugin connection invalid. The dashboard shows project, indexing and connection status; a stale or deleted key is not flagged there — compare the key in the tag with **Settings → Embed code** first ([AISX-W110](https://achlaai.com/en/docs/troubleshooting#AISX-W110)).
- `{"error":"bad_request"}` (HTTP 400) — the key value is malformed ([AISX-W112](https://achlaai.com/en/docs/troubleshooting#AISX-W112)).

<a id="snippet"></a>
## The embed snippet

Replace `YOUR_PUBLIC_KEY` with the key from **Settings → Embed code** (or copy the whole tag from there).

```html
<script src="https://achlaai.com/w.js" data-key="YOUR_PUBLIC_KEY" defer></script>
```

| Attribute | Required | Values | Purpose |
| --- | --- | --- | --- |
| `src` | yes | `https://achlaai.com/w.js` | The widget. It sends its API requests to the same origin it was loaded from — do not copy the file to your own server or CDN. |
| `data-key` | yes | public key, starts with `pk_` | Identifies the site. Missing → [AISX-W101](https://achlaai.com/en/docs/troubleshooting#AISX-W101); malformed → [AISX-W112](https://achlaai.com/en/docs/troubleshooting#AISX-W112). |
| `defer` | recommended | — | Load without blocking the page; the widget mounts once the document is ready. |
| `data-mode` | no | `bubble` · `inline` · `attach` | Overrides the placement mode chosen in the dashboard, for this tag only. |
| `data-attach` | no | CSS selector | The search `<input>` to attach to (used with `attach` mode); overrides the dashboard selector. |
| `data-position` | no | `br` · `bl` · `tr` · `tl` | Corner of the floating button (bubble): bottom-right, bottom-left, top-right, top-left. |
| `data-preview` | never on a live site | `1` | Dashboard preview only: the widget makes no network requests and answers with a canned demo. |

> **Which setting wins.** The tag controls **placement only** (`data-mode`, `data-attach`, `data-position`). Everything visual — theme, accent colour, corner radius, title, placeholder, greeting — comes from the dashboard via the server and cannot be set in the tag. Placement attributes you omit (or give an unknown value) fall back to the dashboard setting.

- Put the tag in the HTML of every page that should show search, just before `</body>`.
- Exactly **one** tag per page. A second copy mounts a second widget ([AISX-W105](https://achlaai.com/en/docs/troubleshooting#AISX-W105)).
- If you add the tag with JavaScript, set `data-key` and the other `data-*` attributes before appending it to the page.

<a id="modes"></a>
## Placement modes

| Mode | What visitors see | Requirement on the page | If the requirement is missing |
| --- | --- | --- | --- |
| `bubble` (default) | A floating “Ask AI” button in a corner that opens a chat panel. | None. | — |
| `inline` | A search box embedded in your content. | An element `<div id="ai-search"></div>` in the page HTML. | Floating button instead + [AISX-W104](https://achlaai.com/en/docs/troubleshooting#AISX-W104). |
| `attach` | Your existing search field opens AI answers in a dropdown on Enter, with a link back to your regular results. | A CSS selector that matches an `<input>` of type `text` or `search`. | Floating button instead + [AISX-W102](https://achlaai.com/en/docs/troubleshooting#AISX-W102) / [AISX-W103](https://achlaai.com/en/docs/troubleshooting#AISX-W103) / [AISX-W106](https://achlaai.com/en/docs/troubleshooting#AISX-W106). |

> **Switching to inline? Add the container first.** Changing the mode to `inline` in the dashboard reaches every page within about 30 seconds ([when changes take effect](https://achlaai.com/en/docs/troubleshooting#changes-take-effect)). Pages without `<div id="ai-search"></div>` fall back to the floating button. The container must be in the page when the widget mounts; one added later by client-side code is not picked up.

For `attach`, only the first element matched by the selector is used. Test the selector on the live page in the browser console: `document.querySelector('input[type="search"]')` (replace with your selector) must return your search input. Dashboard changes to mode or selector need no cache purge — see [When do changes take effect?](https://achlaai.com/en/docs/troubleshooting#changes-take-effect).

> **CMS plugins use one placement mode for the whole site.** The WordPress plugin and the Drupal module each have a single placement setting for the whole site. In **Bubble** or **Attach** they load the widget on every public page; in **Inline** they load it only on pages that contain the shortcode/block, and all other pages get no widget at all (no floating button). A floating button everywhere plus an inline box on one page is not possible with the plugins — use manual tags for that (below).

<a id="mixed-placement"></a>
### Mixed placement with manual tags (bubble everywhere, inline on one page)

With manual tags this works, because `data-mode` on the tag overrides the dashboard mode for that tag:

1. Keep the dashboard mode at **Bubble**.
2. On all pages except the target page, use the normal tag (no `data-mode`).
3. On the target page, use a single tag with `data-mode="inline"` and add `<div id="ai-search"></div>` where the box should appear.
4. Never put two widget tags on one page — the second copy mounts a second widget ([AISX-W105](https://achlaai.com/en/docs/troubleshooting#AISX-W105), install-check [AISX-C303](https://achlaai.com/en/docs/troubleshooting#AISX-C303)).

Target page only — this tag replaces the normal one there.

```html
<script src="https://achlaai.com/w.js" data-key="YOUR_PUBLIC_KEY" data-mode="inline" defer></script>
<div id="ai-search"></div>
```

<a id="platforms"></a>
## Install paths

<a id="install-html"></a>
### Plain HTML / any server-rendered site

1. Copy the tag from **Settings → Embed code** in the dashboard.
2. Paste it into the shared layout/template of your site, just before `</body>`, so it is on every page.
3. For inline mode, also add `<div id="ai-search"></div>` where the search box should appear.
4. Deploy, purge any page cache/CDN cache for the HTML, then run the checks in [Verify the installation](#verify).

<a id="install-wordpress"></a>
### WordPress — official plugin (recommended)

1. Install **Achla AI Search for WordPress** from [WordPress.org](https://wordpress.org/plugins/achlaai/) (current version 0.3.5): **Plugins → Add New**, or upload the ZIP.
2. Activate it, open **Settings → Achla AI Search** and select **Connect**.
3. Complete the ownership step on Achla AI, return to WordPress and wait for the connection and indexing status.
4. Keep **Bubble** placement or choose **Inline** or **Attach** (test an Attach selector before saving), then switch **Show the widget** on.
5. Inline: insert the shortcode `[achla_search]` or the block **Achla AI Search** (`achlaai/inline-search`) on the pages where the search box should appear — it outputs the `#ai-search` container for you.

> **Note.** The plugin loads the widget through its own loader script (not a `/w.js` tag), so a `grep` for `/w.js` will not find it. The plugin uses **one placement mode for the whole site**: with **Inline** it loads the widget only on pages that contain the shortcode or block — other pages show nothing (no floating button) and no console message is printed; in **Bubble** or **Attach** the shortcode/block outputs nothing. For a floating button everywhere plus an inline box on one page, use manual tags instead of the plugin ([Mixed placement](#mixed-placement)). Do not also paste the manual tag while the plugin is active.

<a id="install-wordpress-manual"></a>
### WordPress — manual tag (without the plugin)

Paste the tag into your theme's footer template just before `</body>`, or use a header/footer code-snippet plugin that outputs it on every page. Use either this or the official plugin, never both.

<a id="install-drupal"></a>
### Drupal — official module

1. Install **Achla AI Search for Drupal** (Drupal 10.3+ and 11.3+, PHP 8.1+): `composer require 'drupal/achlaai_search:^0.3'`. A ZIP is also available on [Drupal.org](https://www.drupal.org/project/achlaai_search).
2. Enable the module `achlaai_search` (Extend page, or `drush en achlaai_search`).
3. Open **Administration → Configuration → Web services → Achla AI Search** (`/admin/config/services/achlaai-search`) and connect the site.
4. Choose placement: **Bubble**, **Inline** (place the block **Achla AI Search** in a region via Block layout), or **Attach** (the selector must pass the browser preview before it can be saved).

> **Note.** The module uses **one placement mode for the whole site**: in **Bubble** or **Attach** it adds the widget to every non-admin page; in **Inline** only the **Achla AI Search** block loads it, so pages without the block get no widget at all (no floating button). The block outputs nothing unless the placement is **Inline**. Like the WordPress plugin, it loads the widget through its own loader, not a `/w.js` tag.

<a id="install-spa"></a>
### Single-page apps (React, Next.js, Vue …)

- Add the tag once, in the root HTML document/layout, so it is loaded once per full page load. The widget mounts once and has no JavaScript API for re-mounting.
- **Bubble** works best: the button is appended to `<body>` and survives client-side navigation as long as your app does not replace `<body>`.
- **Inline** needs `<div id="ai-search"></div>` present when the widget mounts (server-rendered HTML). If your router later removes or re-creates that element, the inline box disappears until the next full page load.
- **Attach** binds to the input element that exists at mount time; if the app re-renders that input, the binding is lost.

<a id="verify"></a>
## Verify the installation

1. The tag is in the served HTML (manual installs). Expect exactly one match:
2. The key is enabled — must contain `"enabled":true`:
3. In the browser, open the page with DevTools → Console: there must be no lines starting with `[ai-search]`. Any such line carries an `AISX-…` code — see [Troubleshooting](https://achlaai.com/en/docs/troubleshooting).
4. The widget is visible: the floating button (bubble), the inline box (inline), or a dropdown when you press Enter in your search field (attach).
5. Ask a test question about your site: the answer should cite sources from your pages.
6. Run the installation check (replace the URL with a page of your site): `curl -s "https://achlaai.com/api/install-check?url=https://YOUR-SITE.example"`. It downloads the page, finds the tag, checks the key and the placement, and returns `AISX-C3xx` findings with fixes as JSON — `AISX-C309` means the installation looks correct. The **Check installation** button in the dashboard runs the same check for your site.

Step 1 — replace the URL with a page of your site.

```bash
curl -s "https://YOUR-SITE.example" | grep -o '<script[^>]*/w\.js[^>]*>'
```

Step 2 — replace the key.

```bash
curl -s "https://achlaai.com/api/widget-config?key=YOUR_PUBLIC_KEY"
```

Step 4, in the browser console — a value above 0 means the widget has mounted.

```javascript
document.querySelectorAll('.aisx-btn, .aisx-inline, .aisx-drop').length
```

<a id="csp"></a>
## Content-Security-Policy

If your site sends a Content-Security-Policy header, it must allow the widget origin. The widget loads its script from that origin, requests its configuration and answers from the same origin, and injects its stylesheet as a `<style>` element:

Add these sources to your existing directives (keep your other sources).

```text
script-src https://achlaai.com;
connect-src https://achlaai.com;
style-src 'unsafe-inline';
```

A blocked script or request shows up in the browser console as a CSP violation (not as an `[ai-search]` line), or as [AISX-W111](https://achlaai.com/en/docs/troubleshooting#AISX-W111) / [AISX-W121](https://achlaai.com/en/docs/troubleshooting#AISX-W121) when the configuration or a search request is blocked.

<a id="dont"></a>
## What not to do

- Do not include the tag twice (theme + tag manager, or plugin + manual tag).
- Do not edit the key by hand — copy it from the dashboard.
- Do not copy `w.js` to your own server or CDN: the widget sends requests to the origin it was loaded from, so a copy calls the wrong server and misses updates. Always load it from `https://achlaai.com/w.js`.
- Do not set `data-preview="1"` on a live site.
- Do not block `https://achlaai.com` in your CSP (see [Content-Security-Policy](#csp)).

---

# Troubleshoot the Achla AI widget

> Why the Achla AI search widget does not appear or does not answer: a decision tree, every console message and API error code (AISX-…), and how to fix each.

HTML: https://achlaai.com/en/docs/troubleshooting · Markdown: https://achlaai.com/docs/troubleshooting.md

<a id="triage"></a>
## Quick triage: the widget does not appear

Work through these steps in order — each one rules out a whole class of causes.

1. **Is the tag in the page HTML?** Run the command below; no match means the tag is not installed on this page or an old cached copy of the page is served — add the tag and purge the page cache. (CMS plugins use their own loader, so `/w.js` does not appear there — check the plugin's status page instead.)
2. **Is the key enabled?** Run the `widget-config` command below. `{"enabled":false}` → the key is unknown or replaced, the project is not active, indexing is not finished, or ownership/plugin connection is invalid. First compare the key in the tag with **Settings → Embed code**: a stale or deleted key is not flagged in the dashboard. If they differ, replace the whole tag with the current one. If they match, the dashboard (**Overview**) shows project, indexing and connection status — see [AISX-W110](#AISX-W110). Do not change CSP or caching for this.
3. **Enabled, but nothing visible?** If the command returns `"enabled":true`, open the page with DevTools → Console and look for lines starting with `[ai-search]`. Each carries an `AISX-…` code — find it in [Console messages](#console-messages).
4. **Console is silent?** See [Silent failures](#silent-failures): a CSP that blocks the script, a plugin that did not output the loader, a CMS plugin in Inline mode on a page without its shortcode/block (expected — no floating button there), or page CSS covering the widget.

1 — expect exactly one `<script …/w.js …>` tag.

```bash
curl -s "https://YOUR-SITE.example" | grep -o '<script[^>]*/w\.js[^>]*>'
```

2 — expect `"enabled":true`.

```bash
curl -s "https://achlaai.com/api/widget-config?key=YOUR_PUBLIC_KEY"
```

> **Inline mode and the floating button.** If you expected an inline search box but see the floating button, the page has no `<div id="ai-search"></div>` — [AISX-W104](#AISX-W104). If you see both, the widget is included twice — [AISX-W105](#AISX-W105).

<a id="silent-failures"></a>
## Silent failures (no [ai-search] line in the console)

| Situation | How to recognise it | Fix |
| --- | --- | --- |
| The script is blocked by the site's CSP | The console shows a Content-Security-Policy violation for `w.js` (browser message, not `[ai-search]`); the Network tab shows the request as blocked. | Allow `https://achlaai.com` in `script-src` and `connect-src` — see [the install guide](https://achlaai.com/en/docs/install#csp). |
| The tag is missing on this page or the HTML is cached | The `grep` command in [Quick triage](#triage) finds nothing. | Add the tag (`<script src="https://achlaai.com/w.js" data-key="YOUR_PUBLIC_KEY" defer></script>`) to the page template and purge the page/CDN cache. |
| CMS plugin with Inline placement: no floating button on other pages | Pages without the WordPress shortcode `[achla_search]` / “Achla AI Search” block, or without the Drupal “Achla AI Search” block, show no widget at all. This is expected: the plugins use one placement mode for the whole site and, in Inline, load the widget only where the shortcode/block is rendered. | Insert the shortcode or block on that page, or choose Bubble placement in the plugin settings. For a floating button everywhere plus an inline box on one page, use manual tags — see [Mixed placement](https://achlaai.com/en/docs/install#mixed-placement). |
| A CMS plugin did not output the widget | No widget, no console line. The plugins record placement/release problems as `data-achla…` attributes on `<html>`: run `document.documentElement.getAttributeNames().filter(n => n.startsWith('data-achla'))` in the console. | Open the plugin settings: check the connection, indexing status, the “show the widget” switch and the placement diagnostics; reconnect if the connection was revoked. |
| The widget is covered by page elements | `document.querySelectorAll('.aisx-btn, .aisx-inline, .aisx-drop').length` is above 0, but nothing is visible. | The floating button and panel use `z-index: 2147483000`; check for theme elements with a higher z-index or for CSS that hides the `#ai-search` container. |

Older widget builds printed the same messages without the `AISX-…` code (for example `[ai-search] inline: no <div id="ai-search"> on this page, falling back to bubble`). Match them by text against the signals below.

<a id="changes-take-effect"></a>
## When do changes take effect?

- **Dashboard settings** (placement mode, attach selector, appearance) reach visitors on the next page load within about 30 seconds. `/api/widget-config` is served with `Cache-Control: no-store`; each server instance caches widget settings for 30 seconds and the project record for 5 seconds. The tag on your page does not change, so no page or CDN cache purge is needed.
- **The widget code** (`/w.js`) is served with `Cache-Control: public, max-age=3600, must-revalidate`, so a new widget version can take up to an hour to reach a visitor's browser.
- **Changes to the tag itself** (adding it, `data-mode`, `data-attach`, `data-position`, the key) are changes to your page HTML and take effect when your site serves the new HTML.

<a id="console-messages"></a>
## Console messages (AISX-W1xx)

Every message the widget prints has the form `[ai-search] <CODE> <message> — <link>`, where the link points to the matching section below.

| Code | Signal | Meaning |
| --- | --- | --- |
| [AISX-W101](#AISX-W101) | `AISX-W101 missing data-key` | The script tag has no data-key |
| [AISX-W102](#AISX-W102) | `AISX-W102 attach: invalid selector, falling back to bubble` | Attach selector is not valid CSS |
| [AISX-W103](#AISX-W103) | `AISX-W103 attach: no input matched the selector, falling back to bubble` | Attach selector matched nothing on this page |
| [AISX-W104](#AISX-W104) | `AISX-W104 inline: no <div id="ai-search"> on this page, falling back to bubble` | Inline mode, but the page has no #ai-search container |
| [AISX-W105](#AISX-W105) | `AISX-W105 inline: target is already used, falling back to bubble` | The #ai-search container is already used by another copy of the widget |
| [AISX-W106](#AISX-W106) | `AISX-W106 attach: matched element is not a free text input, falling back to bubble` | Attach selector matched an element that cannot be used |
| [AISX-W110](#AISX-W110) | `AISX-W110 widget is disabled for this key (unknown key, index not ready, or access revoked) — check your dashboard` | The widget is disabled for this key |
| [AISX-W111](#AISX-W111) | `AISX-W111 could not load widget configuration (network, CSP or server error)` | The widget configuration could not be loaded |
| [AISX-W112](#AISX-W112) | `AISX-W112 data-key has an invalid format` | The data-key value is malformed |
| [AISX-W120](#AISX-W120) | `AISX-W120 search request failed:` | A search request returned an error |
| [AISX-W121](#AISX-W121) | `AISX-W121 search request did not complete (network error or timeout)` | A search request did not complete |

<a id="AISX-W101"></a>
### AISX-W101 — The script tag has no data-key

Printed with `console.error`.

```text
[ai-search] AISX-W101 missing data-key — <link to this section>
```

**Cause.** The `<script>` that loads the widget has no `data-key` attribute (or it is empty). The widget cannot tell which site it belongs to, stops immediately and renders nothing.

**Fix.** Copy the embed code again from your dashboard (**Settings → Embed code**): it already contains `data-key="pk_…"`. If you add the tag with JavaScript, set `data-key` on the element before you append it to the page.

<a id="AISX-W102"></a>
### AISX-W102 — Attach selector is not valid CSS

Printed with `console.warn`.

```text
[ai-search] AISX-W102 attach: invalid selector, falling back to bubble — <link to this section>
```

**Cause.** Placement mode is `attach`, but the selector (from `data-attach` or from the dashboard) is not a valid CSS selector — `document.querySelector()` threw an error. The widget shows the floating button (bubble) instead.

**Fix.** Use a valid CSS selector for your site's search field, for example `input[type="search"]` or `#search-input`. Set it in the dashboard (**Settings → Widget mode**) or in `data-attach` in the tag, or switch placement back to bubble. Dashboard changes reach visitors on the next page load within about 30 seconds — no cache purge needed ([When do changes take effect?](#changes-take-effect)). After saving, reload the page and run `document.querySelector('<your selector>')` in the browser console — it must return the search `<input>` (type `text` or `search`), and the console must no longer show AISX-W102.

<a id="AISX-W103"></a>
### AISX-W103 — Attach selector matched nothing on this page

Printed with `console.warn`.

```text
[ai-search] AISX-W103 attach: no input matched the selector, falling back to bubble — <link to this section>
```

**Cause.** Placement mode is `attach`, but no selector is configured, or the selector matches no element on this page at the moment the widget mounts. The widget shows the floating button (bubble) instead.

**Fix.** 1. Test the selector before saving it: on the live page, run `document.querySelector('<selector>')` in the browser console — it must return the search `<input>` (type `text` or `search`) that exists when the page loads. Adjust the selector until it does. 2. Save it in the dashboard (**Settings → Widget mode**) or in `data-attach` on the tag — or switch to bubble. If the field exists only on some pages, the bubble on the other pages is expected. 3. Reload the page and run the same `document.querySelector('<selector>')` again: it must still return the input, and the console must no longer show AISX-W103. Dashboard changes reach visitors on the next page load within about 30 seconds — no cache purge needed ([When do changes take effect?](#changes-take-effect)).

<a id="AISX-W104"></a>
### AISX-W104 — Inline mode, but the page has no #ai-search container

Printed with `console.warn`.

```text
[ai-search] AISX-W104 inline: no <div id="ai-search"> on this page, falling back to bubble — <link to this section>
```

**Cause.** Placement mode is `inline` (set in the dashboard or with `data-mode="inline"`), but no element with `id="ai-search"` exists when the widget mounts. The widget shows the floating button (bubble) instead of the inline search box.

**Fix.** Add `<div id="ai-search"></div>` to the page HTML exactly where the search box should appear (WordPress plugin: the `[achla_search]` shortcode or the “Achla AI Search” block; Drupal module: place the “Achla AI Search” block). Or switch placement back to bubble in the dashboard. A container inserted later by client-side JavaScript is not picked up. Dashboard changes reach visitors on the next page load within about 30 seconds — no cache purge needed ([When do changes take effect?](#changes-take-effect)). After the change, reload the page: the console must no longer show AISX-W104.

<a id="AISX-W105"></a>
### AISX-W105 — The #ai-search container is already used by another copy of the widget

Printed with `console.warn`.

```text
[ai-search] AISX-W105 inline: target is already used, falling back to bubble — <link to this section>
```

**Cause.** The `#ai-search` element was already claimed by another instance of the widget — almost always because the widget script is included twice on the page. The second copy falls back to the floating button, so the page shows both.

**Fix.** Keep exactly one widget tag per page. In the browser console, `document.querySelectorAll('script[src$="/w.js"], script[src*="/widget/releases/"]').length` must be `1`. Remove the extra copy (theme template, tag manager, or a plugin plus a manual tag).

<a id="AISX-W106"></a>
### AISX-W106 — Attach selector matched an element that cannot be used

Printed with `console.warn`.

```text
[ai-search] AISX-W106 attach: matched element is not a free text input, falling back to bubble — <link to this section>
```

**Cause.** Placement mode is `attach` and the selector matched an element, but it is not an `<input>` of type `text` or `search` (for example a `<form>`, a wrapper `<div>`, a button or a `<textarea>`), or another copy of the widget has already attached to it. The widget shows the floating button (bubble) instead. Only the first element matched by the selector is checked.

**Fix.** Point the selector at the search `<input>` itself, e.g. `form.search input[type="search"]` instead of `form.search`. If the field is already taken, remove the duplicate widget tag (see [AISX-W105](#AISX-W105)). Dashboard changes reach visitors on the next page load within about 30 seconds — no cache purge needed ([When do changes take effect?](#changes-take-effect)). After saving, reload the page and run `document.querySelector('<your selector>')` in the browser console — it must return the search `<input>` (type `text` or `search`), and the console must no longer show AISX-W106.

<a id="AISX-W110"></a>
### AISX-W110 — The widget is disabled for this key

Printed with `console.warn`.

```text
[ai-search] AISX-W110 widget is disabled for this key (unknown key, index not ready, or access revoked) — check your dashboard — <link to this section>
```

**Cause.** `/api/widget-config` answered `{"enabled":false}`. Possible reasons: the key is unknown or was deleted/replaced, the project is not active, the search index is not ready yet, or site ownership / the CMS plugin connection is no longer valid. The public endpoint deliberately does not say which. The widget renders nothing.

**Fix.** 1. Compare the `data-key` in the page's tag with the key in **Settings → Embed code**. If they differ (the old key was deleted or replaced), replace the whole tag with the current one — a stale or deleted key is not flagged in the dashboard, where the project can look healthy. 2. If the keys match, open **Overview**: project status, index readiness and site connection are shown there. If you connected through the WordPress or Drupal plugin, check the connection status in the plugin settings and reconnect if needed. Do not change CSP or caching — the request itself succeeded. Re-check with the `widget-config` check in [Quick triage](#triage): it must return `"enabled":true`.

<a id="AISX-W111"></a>
### AISX-W111 — The widget configuration could not be loaded

Printed with `console.warn`.

```text
[ai-search] AISX-W111 could not load widget configuration (network, CSP or server error) — <link to this section>
```

**Cause.** Three attempts to `GET /api/widget-config` failed: network error or timeout (1.5 s per attempt), the request was blocked by the site's Content-Security-Policy (`connect-src`), the server kept answering HTTP 429/5xx, or the response was not valid JSON. Without a configuration the widget renders nothing (it never shows itself without an explicit `"enabled":true`).

**Fix.** Open DevTools → Network and find the `widget-config` request. Blocked by CSP → allow the widget origin in `connect-src` (see the install guide, “Content-Security-Policy”). 5xx/timeouts → retry in a few minutes. Check the endpoint directly with the `widget-config` check in [Quick triage](#triage).

<a id="AISX-W112"></a>
### AISX-W112 — The data-key value is malformed

Printed with `console.error`.

```text
[ai-search] AISX-W112 data-key has an invalid format — <link to this section>
```

**Cause.** `/api/widget-config` answered HTTP 400: the `data-key` value is not a plausible public key (allowed: letters, digits, `_`, `.`, `-`, at most 128 characters). Typical causes: a typo, a truncated key, extra spaces or quotes, or a placeholder such as `pk_XXXX` left in the snippet. The widget renders nothing.

**Fix.** Copy the exact key from **Settings → Embed code** in your dashboard (it starts with `pk_`) and replace the whole `data-key` value. Do not edit the key by hand.

<a id="AISX-W120"></a>
### AISX-W120 — A search request returned an error

Printed with `console.warn`.

```text
[ai-search] AISX-W120 search request failed: <error code> — <link to this section>
```

**Cause.** The visitor asked a question and `/api/search` answered with an error. The console line continues with the server's error code, e.g. `AISX-W120 search request failed: quota_exceeded`; it ends with `unknown` when the response carried no recognisable code (for example an HTML error page from a proxy or CDN instead of JSON). The visitor sees a short message in the widget.

**Fix.** Look up the trailing code in the [search API error table](#api-errors) (AISX-A201…AISX-A214) — each entry explains the cause and the fix.

<a id="AISX-W121"></a>
### AISX-W121 — A search request did not complete

Printed with `console.warn`.

```text
[ai-search] AISX-W121 search request did not complete (network error or timeout) — <link to this section>
```

**Cause.** The request to `/api/search` failed before any response arrived (network error, request blocked by the site's CSP `connect-src`, or no answer within 60 seconds). The visitor sees an error message in the widget.

**Fix.** Open DevTools → Network and repeat the question. Blocked by CSP → allow the widget origin in `connect-src`. Timeouts → retry; if they persist, contact support from your dashboard with the time of the request.

<a id="api-errors"></a>
## Search API errors (AISX-A2xx)

When a visitor's question fails, `/api/search` answers with a JSON body containing `error` (and a visitor-facing `message`). Find it in DevTools → Network → the `search` request → Response, or at the end of the console line [AISX-W120](#AISX-W120).

| Code | Signal | Meaning |
| --- | --- | --- |
| [AISX-A201](#AISX-A201) | `missing_key_or_query` | Key or question is missing |
| [AISX-A202](#AISX-A202) | `bad_request` | Malformed request |
| [AISX-A203](#AISX-A203) | `payload_too_large` | Request body too large |
| [AISX-A204](#AISX-A204) | `query_too_long` | Question too long |
| [AISX-A205](#AISX-A205) | `invalid_key` | Unknown or inactive key |
| [AISX-A206](#AISX-A206) | `origin_not_allowed` | The widget is used on a site the key is not registered for |
| [AISX-A207](#AISX-A207) | `project_inactive` | Project is not active |
| [AISX-A208](#AISX-A208) | `not_ready` | Search index is not ready |
| [AISX-A209](#AISX-A209) | `project_payment_overdue` | Subscription payment is overdue |
| [AISX-A210](#AISX-A210) | `rate_limited` | Too many requests |
| [AISX-A211](#AISX-A211) | `daily_cap_exceeded` | Daily safety cap reached |
| [AISX-A212](#AISX-A212) | `quota_exceeded` | Search quota used up |
| [AISX-A213](#AISX-A213) | `quota_unavailable` | Quota check temporarily unavailable |
| [AISX-A214](#AISX-A214) | `answer_failed` | The answer could not be generated |

<a id="AISX-A201"></a>
### AISX-A201 — Key or question is missing

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 400 | `missing_key_or_query` | That question couldn't be sent. Please try again. |

**Cause.** The JSON body has an empty or missing `key` or `query`. The widget always sends both, so this normally comes from a hand-written API call.

**Fix.** Send `{"key":"pk_…","query":"…"}` with `Content-Type: application/json`.

<a id="AISX-A202"></a>
### AISX-A202 — Malformed request

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 400 | `bad_request` | That question couldn't be sent. Please try again. |

**Cause.** The request body is not valid JSON, or the question is empty after control characters and extra whitespace are removed.

**Fix.** Send a valid JSON body with a non-empty `query`. With the stock widget this is rare — retry the question.

<a id="AISX-A203"></a>
### AISX-A203 — Request body too large

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 413 | `payload_too_large` | Your question is too long. Please shorten it to 500 characters or fewer. |

**Cause.** The request body exceeds 16 KB, or the question exceeds 4096 characters.

**Fix.** Shorten the question (questions longer than 500 characters are rejected anyway, see [AISX-A204](#AISX-A204)).

<a id="AISX-A204"></a>
### AISX-A204 — Question too long

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 400 | `query_too_long` | Your question is too long. Please shorten it to 500 characters or fewer. |

**Cause.** After whitespace is collapsed, the question is longer than 500 characters.

**Fix.** Ask a shorter question (at most 500 characters).

<a id="AISX-A205"></a>
### AISX-A205 — Unknown or inactive key

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 401 | `invalid_key` | Search isn't available on this site. |

**Cause.** The key has an invalid format, does not exist, or has been deactivated (for example replaced by a new key).

**Fix.** Compare `data-key` on the page with **Settings → Embed code** in your dashboard; if they differ (the old key was deleted or replaced), replace the whole tag with the current one. A stale or deleted key is not flagged in the dashboard — the project can look healthy there. The same key makes `/api/widget-config` answer `{"enabled":false}` ([AISX-W110](#AISX-W110)).

<a id="AISX-A206"></a>
### AISX-A206 — The widget is used on a site the key is not registered for

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 403 | `origin_not_allowed` | Search isn't available on this site. |

**Cause.** The key is bound to the site registered for its project, and the request's `Origin` is not one of its origins. Allowed: the registered host over `http` or `https`, plus its `www.` / bare-domain counterpart. Other domains, staging subdomains and non-default ports are rejected.

**Fix.** Use the widget on the registered site. For another domain, register that site separately in the dashboard (each site has its own key), or contact support.

<a id="AISX-A207"></a>
### AISX-A207 — Project is not active

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 403 | `project_inactive` | Search isn't available on this site. |

**Cause.** The project behind the key is not active (suspended, being deleted, or blocked by billing), or its site ownership / CMS plugin connection is no longer valid (for example the plugin was disconnected).

**Fix.** Check **Overview** and **Billing** in your dashboard. If the site uses the WordPress or Drupal plugin, open the plugin settings and reconnect.

<a id="AISX-A208"></a>
### AISX-A208 — Search index is not ready

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 409 | `not_ready` | Search is still being set up on this site. Please check back a little later. |

**Cause.** The site's search index is not ready yet — the first indexing is still running or has not finished successfully.

**Fix.** Wait for indexing to finish; **Overview** in your dashboard shows the status. The widget does not render at all until the index is ready ([AISX-W110](#AISX-W110)).

<a id="AISX-A209"></a>
### AISX-A209 — Subscription payment is overdue

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 402 | `project_payment_overdue` | AI search is currently unavailable on this site. Please try again later. |

**Cause.** The subscription is past due or paused (or has ended) for longer than the grace period, so AI search is switched off before any paid processing.

**Fix.** Open **Billing** in your dashboard and settle the payment or update the payment method. Search resumes once the subscription is active.

<a id="AISX-A210"></a>
### AISX-A210 — Too many requests

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 429 | `rate_limited` | Search is busy right now. Please wait N seconds and try again. |

**Cause.** Too many questions in a short time — from one visitor IP address (20 per minute) or for the whole site (per-site limit per minute). The `Retry-After` header says how many seconds to wait.

**Fix.** Usually transient: wait and retry. If you are load-testing or a bot is hammering the widget, slow down.

<a id="AISX-A211"></a>
### AISX-A211 — Daily safety cap reached

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 429 | `daily_cap_exceeded` | Search is unavailable for the rest of today. Please try again tomorrow. |

**Cause.** The site reached its daily ceiling of AI searches — a protection against a copied public key being abused. It resets at the next midnight UTC (`Retry-After` gives the seconds).

**Fix.** Wait for the reset. If your genuine traffic exceeds the cap, contact support from your dashboard.

<a id="AISX-A212"></a>
### AISX-A212 — Search quota used up

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 402 | `quota_exceeded` | A list of the most relevant pages on the site instead of an AI answer; when no pages can be listed: “AI search is temporarily unavailable. Please try again later.” |

**Cause.** The plan's search allowance for the current billing period and any prepaid extra searches are used up (the Free plan stops at its monthly limit). AI answers pause until more searches are available.

**Fix.** In **Billing**: buy extra searches, enable auto top-up, or upgrade the plan — or wait until the allowance renews at the start of the next billing period.

<a id="AISX-A213"></a>
### AISX-A213 — Quota check temporarily unavailable

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 503 | `quota_unavailable` | Search is temporarily unavailable. Please try again in a moment. |

**Cause.** The quota service could not be reached for this request. Nothing was charged.

**Fix.** Retry in a moment. If it persists, contact support from your dashboard.

<a id="AISX-A214"></a>
### AISX-A214 — The answer could not be generated

| HTTP status | `error` in the JSON response | What the visitor sees |
| --- | --- | --- |
| 502 | `answer_failed` | The answer couldn't be generated. Please try again. |

**Cause.** Generating the answer failed upstream. The search is not counted — it is returned to your quota.

**Fix.** Retry the question. If it keeps failing, contact support from your dashboard with the time of the request.

<a id="install-check-findings"></a>
## Install-check findings (AISX-C3xx)

Codes returned in `findings[].code` by the Achla AI installation check. The checker downloads one page as served (it does not run JavaScript) and compares it with the public widget configuration of the key it finds.

Run the check with `GET https://achlaai.com/api/install-check?url=<page URL>` (public, JSON, no key needed; results are cached for 60 seconds and rate-limited per IP), or with the **Check installation** button in the Achla AI dashboard (**Overview** and **Settings**, under the embed code). The response lists `findings` (`code`, `severity`, `title`, `cause`, `fix`, `docs`; `AISX-C301` also carries `detail` — the concrete reason the page could not be fetched) and the `limits` of the check.

Replace the URL with a page of your site that should show the widget.

```bash
curl -s "https://achlaai.com/api/install-check?url=https://YOUR-SITE.example"
```

| Code | Signal | Meaning |
| --- | --- | --- |
| [AISX-C301](#AISX-C301) | `page_unreachable` | The page could not be fetched |
| [AISX-C302](#AISX-C302) | `snippet_missing` | No widget tag in the page HTML |
| [AISX-C303](#AISX-C303) | `snippet_duplicate` | The widget tag appears more than once |
| [AISX-C304](#AISX-C304) | `key_missing` | The widget tag has no usable data-key |
| [AISX-C305](#AISX-C305) | `widget_disabled` | The widget is disabled for this key |
| [AISX-C306](#AISX-C306) | `inline_container_missing` | Inline mode without an #ai-search container |
| [AISX-C307](#AISX-C307) | `attach_selector_no_match` | The attach selector matches nothing in the page HTML |
| [AISX-C308](#AISX-C308) | `origin_mismatch` | The key belongs to a different site |
| [AISX-C309](#AISX-C309) | `ok` | Installation looks correct |
| [AISX-C310](#AISX-C310) | `foreign_script_host` | The widget script is loaded from an unexpected host |

<a id="AISX-C301"></a>
### AISX-C301 — The page could not be fetched

Finding id: `page_unreachable` (severity: error).

**Cause.** The checker could not download the page: DNS or connection error, timeout, a non-2xx HTTP status, a non-public address, or a firewall/WAF that blocks automated requests. The `detail` field of the finding names the actual reason (for example HTTP 403, a timeout, or a non-HTML response).

**Fix.** Make sure the URL opens publicly without a login. If a WAF blocks it, the browser checks below still work; see also the crawler page (`/en/bot`).

<a id="AISX-C302"></a>
### AISX-C302 — No widget tag in the page HTML

Finding id: `snippet_missing` (severity: error).

**Cause.** Neither a widget `<script>` (`/w.js`) nor a CMS plugin loader was found in the HTML as served. The checker does not run JavaScript, so a tag added by a tag manager or by client-side code is invisible to it.

**Fix.** Add the embed code from your dashboard before `</body>`. If you insert it through a tag manager or JavaScript, verify in the browser instead: the console must show no `[ai-search]` errors and the widget must appear. Also purge any page cache after adding the tag.

<a id="AISX-C303"></a>
### AISX-C303 — The widget tag appears more than once

Finding id: `snippet_duplicate` (severity: warn).

**Cause.** The page includes the widget more than once. Each copy mounts its own widget (two buttons, or [AISX-W105](#AISX-W105) for inline).

**Fix.** Keep exactly one tag per page — remove the copy from the theme, the tag manager, or the manual snippet if a plugin already adds it.

<a id="AISX-C304"></a>
### AISX-C304 — The widget tag has no usable data-key

Finding id: `key_missing` (severity: error).

**Cause.** The widget tag was found, but its `data-key` attribute is missing, empty, or malformed ([AISX-W101](#AISX-W101), [AISX-W112](#AISX-W112)).

**Fix.** Copy the embed code again from **Settings → Embed code** in your dashboard.

<a id="AISX-C305"></a>
### AISX-C305 — The widget is disabled for this key

Finding id: `widget_disabled` (severity: error).

**Cause.** `/api/widget-config` returns `{"enabled":false}` for the key on the page: the key is unknown or was deleted/replaced, the project is not active, the index is not ready, or the site connection is no longer valid ([AISX-W110](#AISX-W110)).

**Fix.** First compare the key on the page with **Settings → Embed code**; if they differ (the old key was deleted or replaced), replace the whole tag with the current one. The dashboard shows project, indexing and connection status; a stale or deleted key is not flagged there. If the keys match, open **Overview**.

<a id="AISX-C306"></a>
### AISX-C306 — Inline mode without an #ai-search container

Finding id: `inline_container_missing` (severity: error).

**Cause.** The widget is set to `inline`, but the page HTML has no element with `id="ai-search"`. Visitors get the floating button instead ([AISX-W104](#AISX-W104)).

**Fix.** Add `<div id="ai-search"></div>` where the search box should appear (WordPress: shortcode `[achla_search]` or the “Achla AI Search” block; Drupal: the “Achla AI Search” block), or switch placement to bubble.

<a id="AISX-C307"></a>
### AISX-C307 — The attach selector matches nothing in the page HTML

Finding id: `attach_selector_no_match` (severity: warn).

**Cause.** The widget is set to `attach`, but the selector does not match a text/search `<input>` in the HTML as served. Visitors get the floating button instead ([AISX-W103](#AISX-W103), [AISX-W106](#AISX-W106)). A field rendered by JavaScript is invisible to the checker.

**Fix.** Correct the selector so that it targets the search `<input>`; verify in the browser console with `document.querySelector('<selector>')`.

<a id="AISX-C308"></a>
### AISX-C308 — The key belongs to a different site

Finding id: `origin_mismatch` (severity: error).

**Cause.** The key on this page is registered for another site, so searches from this page are rejected with `origin_not_allowed` ([AISX-A206](#AISX-A206)).

**Fix.** Use the key of the project registered for this site, or register this site separately in the dashboard.

<a id="AISX-C309"></a>
### AISX-C309 — Installation looks correct

Finding id: `ok` (severity: info).

**Cause.** The tag is present once, the key is enabled, and the placement requirements are met in the page HTML.

**Fix.** Nothing to fix. Open the page in a browser and ask a test question to confirm an answer with sources.

<a id="AISX-C310"></a>
### AISX-C310 — The widget script is loaded from an unexpected host

Finding id: `foreign_script_host` (severity: warn).

**Cause.** The `w.js` tag points to a host other than the official widget origin — for example a self-hosted or CDN-cached copy. The widget derives its API address from its own script URL, so such a copy calls the wrong server and does not receive updates.

**Fix.** Load the script exactly as in the embed code from your dashboard; do not copy `w.js` to your own server or CDN.

<a id="indexing"></a>
## Search does not know a page

- **Plan page limit.** Each plan indexes up to a fixed number of pages; pages beyond the limit are not indexed. Check the plan in **Billing**.
- **robots.txt and firewalls.** The Achla AI crawler respects `robots.txt`. A WAF or bot protection that blocks it leaves pages unindexed — see the [crawler page](https://achlaai.com/en/bot) for how to identify and allow it.
- **JavaScript-only content.** Pages whose text is rendered only in the browser may be indexed with little or no text.
- **New or changed pages** are picked up only when the site is re-crawled, not instantly.

<a id="help"></a>
## Still stuck

Open **Support** in the Achla AI dashboard and include: the page URL, the exact `[ai-search]` console lines (with their `AISX-…` codes), and the output of the `widget-config` command above.

---

# Diagnostic code catalog

| Code | Signal | Where | Meaning | Fix |
| --- | --- | --- | --- | --- |
| [AISX-W101](https://achlaai.com/en/docs/troubleshooting#AISX-W101) | `AISX-W101 missing data-key` | console.error | The script tag has no data-key | Copy the embed code again from your dashboard (**Settings → Embed code**): it already contains `data-key="pk_…"`. If you add the tag with JavaScript, set `data-key` on the element before you append it to the page. |
| [AISX-W102](https://achlaai.com/en/docs/troubleshooting#AISX-W102) | `AISX-W102 attach: invalid selector, falling back to bubble` | console.warn | Attach selector is not valid CSS | Use a valid CSS selector for your site's search field, for example `input[type="search"]` or `#search-input`. Set it in the dashboard (**Settings → Widget mode**) or in `data-attach` in the tag, or switch placement back to bubble. Dashboard changes reach visitors on the next page load within about 30 seconds — no cache purge needed ([When do changes take effect?](https://achlaai.com/en/docs/troubleshooting#changes-take-effect)). After saving, reload the page and run `document.querySelector('<your selector>')` in the browser console — it must return the search `<input>` (type `text` or `search`), and the console must no longer show AISX-W102. |
| [AISX-W103](https://achlaai.com/en/docs/troubleshooting#AISX-W103) | `AISX-W103 attach: no input matched the selector, falling back to bubble` | console.warn | Attach selector matched nothing on this page | 1. Test the selector before saving it: on the live page, run `document.querySelector('<selector>')` in the browser console — it must return the search `<input>` (type `text` or `search`) that exists when the page loads. Adjust the selector until it does. 2. Save it in the dashboard (**Settings → Widget mode**) or in `data-attach` on the tag — or switch to bubble. If the field exists only on some pages, the bubble on the other pages is expected. 3. Reload the page and run the same `document.querySelector('<selector>')` again: it must still return the input, and the console must no longer show AISX-W103. Dashboard changes reach visitors on the next page load within about 30 seconds — no cache purge needed ([When do changes take effect?](https://achlaai.com/en/docs/troubleshooting#changes-take-effect)). |
| [AISX-W104](https://achlaai.com/en/docs/troubleshooting#AISX-W104) | `AISX-W104 inline: no <div id="ai-search"> on this page, falling back to bubble` | console.warn | Inline mode, but the page has no #ai-search container | Add `<div id="ai-search"></div>` to the page HTML exactly where the search box should appear (WordPress plugin: the `[achla_search]` shortcode or the “Achla AI Search” block; Drupal module: place the “Achla AI Search” block). Or switch placement back to bubble in the dashboard. A container inserted later by client-side JavaScript is not picked up. Dashboard changes reach visitors on the next page load within about 30 seconds — no cache purge needed ([When do changes take effect?](https://achlaai.com/en/docs/troubleshooting#changes-take-effect)). After the change, reload the page: the console must no longer show AISX-W104. |
| [AISX-W105](https://achlaai.com/en/docs/troubleshooting#AISX-W105) | `AISX-W105 inline: target is already used, falling back to bubble` | console.warn | The #ai-search container is already used by another copy of the widget | Keep exactly one widget tag per page. In the browser console, `document.querySelectorAll('script[src$="/w.js"], script[src*="/widget/releases/"]').length` must be `1`. Remove the extra copy (theme template, tag manager, or a plugin plus a manual tag). |
| [AISX-W106](https://achlaai.com/en/docs/troubleshooting#AISX-W106) | `AISX-W106 attach: matched element is not a free text input, falling back to bubble` | console.warn | Attach selector matched an element that cannot be used | Point the selector at the search `<input>` itself, e.g. `form.search input[type="search"]` instead of `form.search`. If the field is already taken, remove the duplicate widget tag (see [AISX-W105](https://achlaai.com/en/docs/troubleshooting#AISX-W105)). Dashboard changes reach visitors on the next page load within about 30 seconds — no cache purge needed ([When do changes take effect?](https://achlaai.com/en/docs/troubleshooting#changes-take-effect)). After saving, reload the page and run `document.querySelector('<your selector>')` in the browser console — it must return the search `<input>` (type `text` or `search`), and the console must no longer show AISX-W106. |
| [AISX-W110](https://achlaai.com/en/docs/troubleshooting#AISX-W110) | `AISX-W110 widget is disabled for this key (unknown key, index not ready, or access revoked) — check your dashboard` | console.warn | The widget is disabled for this key | 1. Compare the `data-key` in the page's tag with the key in **Settings → Embed code**. If they differ (the old key was deleted or replaced), replace the whole tag with the current one — a stale or deleted key is not flagged in the dashboard, where the project can look healthy. 2. If the keys match, open **Overview**: project status, index readiness and site connection are shown there. If you connected through the WordPress or Drupal plugin, check the connection status in the plugin settings and reconnect if needed. Do not change CSP or caching — the request itself succeeded. Re-check with the `widget-config` check in [Quick triage](https://achlaai.com/en/docs/troubleshooting#triage): it must return `"enabled":true`. |
| [AISX-W111](https://achlaai.com/en/docs/troubleshooting#AISX-W111) | `AISX-W111 could not load widget configuration (network, CSP or server error)` | console.warn | The widget configuration could not be loaded | Open DevTools → Network and find the `widget-config` request. Blocked by CSP → allow the widget origin in `connect-src` (see the install guide, “Content-Security-Policy”). 5xx/timeouts → retry in a few minutes. Check the endpoint directly with the `widget-config` check in [Quick triage](https://achlaai.com/en/docs/troubleshooting#triage). |
| [AISX-W112](https://achlaai.com/en/docs/troubleshooting#AISX-W112) | `AISX-W112 data-key has an invalid format` | console.error | The data-key value is malformed | Copy the exact key from **Settings → Embed code** in your dashboard (it starts with `pk_`) and replace the whole `data-key` value. Do not edit the key by hand. |
| [AISX-W120](https://achlaai.com/en/docs/troubleshooting#AISX-W120) | `AISX-W120 search request failed:` | console.warn | A search request returned an error | Look up the trailing code in the [search API error table](https://achlaai.com/en/docs/troubleshooting#api-errors) (AISX-A201…AISX-A214) — each entry explains the cause and the fix. |
| [AISX-W121](https://achlaai.com/en/docs/troubleshooting#AISX-W121) | `AISX-W121 search request did not complete (network error or timeout)` | console.warn | A search request did not complete | Open DevTools → Network and repeat the question. Blocked by CSP → allow the widget origin in `connect-src`. Timeouts → retry; if they persist, contact support from your dashboard with the time of the request. |
| [AISX-A201](https://achlaai.com/en/docs/troubleshooting#AISX-A201) | `missing_key_or_query` | HTTP 400 | Key or question is missing | Send `{"key":"pk_…","query":"…"}` with `Content-Type: application/json`. |
| [AISX-A202](https://achlaai.com/en/docs/troubleshooting#AISX-A202) | `bad_request` | HTTP 400 | Malformed request | Send a valid JSON body with a non-empty `query`. With the stock widget this is rare — retry the question. |
| [AISX-A203](https://achlaai.com/en/docs/troubleshooting#AISX-A203) | `payload_too_large` | HTTP 413 | Request body too large | Shorten the question (questions longer than 500 characters are rejected anyway, see [AISX-A204](https://achlaai.com/en/docs/troubleshooting#AISX-A204)). |
| [AISX-A204](https://achlaai.com/en/docs/troubleshooting#AISX-A204) | `query_too_long` | HTTP 400 | Question too long | Ask a shorter question (at most 500 characters). |
| [AISX-A205](https://achlaai.com/en/docs/troubleshooting#AISX-A205) | `invalid_key` | HTTP 401 | Unknown or inactive key | Compare `data-key` on the page with **Settings → Embed code** in your dashboard; if they differ (the old key was deleted or replaced), replace the whole tag with the current one. A stale or deleted key is not flagged in the dashboard — the project can look healthy there. The same key makes `/api/widget-config` answer `{"enabled":false}` ([AISX-W110](https://achlaai.com/en/docs/troubleshooting#AISX-W110)). |
| [AISX-A206](https://achlaai.com/en/docs/troubleshooting#AISX-A206) | `origin_not_allowed` | HTTP 403 | The widget is used on a site the key is not registered for | Use the widget on the registered site. For another domain, register that site separately in the dashboard (each site has its own key), or contact support. |
| [AISX-A207](https://achlaai.com/en/docs/troubleshooting#AISX-A207) | `project_inactive` | HTTP 403 | Project is not active | Check **Overview** and **Billing** in your dashboard. If the site uses the WordPress or Drupal plugin, open the plugin settings and reconnect. |
| [AISX-A208](https://achlaai.com/en/docs/troubleshooting#AISX-A208) | `not_ready` | HTTP 409 | Search index is not ready | Wait for indexing to finish; **Overview** in your dashboard shows the status. The widget does not render at all until the index is ready ([AISX-W110](https://achlaai.com/en/docs/troubleshooting#AISX-W110)). |
| [AISX-A209](https://achlaai.com/en/docs/troubleshooting#AISX-A209) | `project_payment_overdue` | HTTP 402 | Subscription payment is overdue | Open **Billing** in your dashboard and settle the payment or update the payment method. Search resumes once the subscription is active. |
| [AISX-A210](https://achlaai.com/en/docs/troubleshooting#AISX-A210) | `rate_limited` | HTTP 429 | Too many requests | Usually transient: wait and retry. If you are load-testing or a bot is hammering the widget, slow down. |
| [AISX-A211](https://achlaai.com/en/docs/troubleshooting#AISX-A211) | `daily_cap_exceeded` | HTTP 429 | Daily safety cap reached | Wait for the reset. If your genuine traffic exceeds the cap, contact support from your dashboard. |
| [AISX-A212](https://achlaai.com/en/docs/troubleshooting#AISX-A212) | `quota_exceeded` | HTTP 402 | Search quota used up | In **Billing**: buy extra searches, enable auto top-up, or upgrade the plan — or wait until the allowance renews at the start of the next billing period. |
| [AISX-A213](https://achlaai.com/en/docs/troubleshooting#AISX-A213) | `quota_unavailable` | HTTP 503 | Quota check temporarily unavailable | Retry in a moment. If it persists, contact support from your dashboard. |
| [AISX-A214](https://achlaai.com/en/docs/troubleshooting#AISX-A214) | `answer_failed` | HTTP 502 | The answer could not be generated | Retry the question. If it keeps failing, contact support from your dashboard with the time of the request. |
| [AISX-C301](https://achlaai.com/en/docs/troubleshooting#AISX-C301) | `page_unreachable` | check (error) | The page could not be fetched | Make sure the URL opens publicly without a login. If a WAF blocks it, the browser checks below still work; see also the crawler page (`/en/bot`). |
| [AISX-C302](https://achlaai.com/en/docs/troubleshooting#AISX-C302) | `snippet_missing` | check (error) | No widget tag in the page HTML | Add the embed code from your dashboard before `</body>`. If you insert it through a tag manager or JavaScript, verify in the browser instead: the console must show no `[ai-search]` errors and the widget must appear. Also purge any page cache after adding the tag. |
| [AISX-C303](https://achlaai.com/en/docs/troubleshooting#AISX-C303) | `snippet_duplicate` | check (warn) | The widget tag appears more than once | Keep exactly one tag per page — remove the copy from the theme, the tag manager, or the manual snippet if a plugin already adds it. |
| [AISX-C304](https://achlaai.com/en/docs/troubleshooting#AISX-C304) | `key_missing` | check (error) | The widget tag has no usable data-key | Copy the embed code again from **Settings → Embed code** in your dashboard. |
| [AISX-C305](https://achlaai.com/en/docs/troubleshooting#AISX-C305) | `widget_disabled` | check (error) | The widget is disabled for this key | First compare the key on the page with **Settings → Embed code**; if they differ (the old key was deleted or replaced), replace the whole tag with the current one. The dashboard shows project, indexing and connection status; a stale or deleted key is not flagged there. If the keys match, open **Overview**. |
| [AISX-C306](https://achlaai.com/en/docs/troubleshooting#AISX-C306) | `inline_container_missing` | check (error) | Inline mode without an #ai-search container | Add `<div id="ai-search"></div>` where the search box should appear (WordPress: shortcode `[achla_search]` or the “Achla AI Search” block; Drupal: the “Achla AI Search” block), or switch placement to bubble. |
| [AISX-C307](https://achlaai.com/en/docs/troubleshooting#AISX-C307) | `attach_selector_no_match` | check (warn) | The attach selector matches nothing in the page HTML | Correct the selector so that it targets the search `<input>`; verify in the browser console with `document.querySelector('<selector>')`. |
| [AISX-C308](https://achlaai.com/en/docs/troubleshooting#AISX-C308) | `origin_mismatch` | check (error) | The key belongs to a different site | Use the key of the project registered for this site, or register this site separately in the dashboard. |
| [AISX-C309](https://achlaai.com/en/docs/troubleshooting#AISX-C309) | `ok` | check (info) | Installation looks correct | Nothing to fix. Open the page in a browser and ask a test question to confirm an answer with sources. |
| [AISX-C310](https://achlaai.com/en/docs/troubleshooting#AISX-C310) | `foreign_script_host` | check (warn) | The widget script is loaded from an unexpected host | Load the script exactly as in the embed code from your dashboard; do not copy `w.js` to your own server or CDN. |