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

# Troubleshooting

> The site never shows connected, no moments appear, a sentence never shows, the wrong sentence showed, the store view is all sample rows, an API call answers 404 or 403, and what to check for each.

Most problems on a directly integrated site come down to one of six things: the origin, the switches, the sheet, the ack, the order feed, or the key. Each section says what you see, what it usually is, and where to look. Shopify-specific problems (the app embed, billing, the bill against Money) are in [Troubleshooting for Shopify](/shopify/troubleshooting).

## The site never shows connected

`state.deployed` is true, `state.connected` stays false.

1. Open a page of the site with the browser's developer tools on the Network tab. Find the request to `sdk.nextintent.ai/<site_id>/settings`. A `403` means the page's origin is not on the allowed list; a `418` means `enabled` is false.
2. Compare the page's exact origin (scheme, host, port) with `urls` on the site record. `https://acme.com` and `https://www.acme.com` are different origins; both should be on the list.
3. If settings answered 200, look for the websocket to the collector. A refused handshake with `token_stale` means the site's origins were changed and this page loaded a cached settings answer; reload once.
4. Nothing at all: the tag is not on this page. Run `GET /v1/sdk/{id}/install-check`.

## No moments appear

Connected is true, Moments is empty after a day of traffic.

* A visitor is not judged in the first 30 seconds of a visit or the first 20 seconds on a page, and never while typing. Very short visits produce no moments.
* The capture toggles: with `behavioral` or `scroll` off the idle rule has little to work with. Turn them on.
* The site type: a site classed as `Personal` or `Nonprofit` has few commercial paths, so "dwelling on a high-intent page" rarely fires. Check `vertical`.
* The moments list defaults to 50 newest; pass `verdict=engage` to see only the engages, and read the `quiet` ones to see what the engine is leaving alone and why.

## A sentence never shows

Engages appear in Moments with a sentence, nothing appears on the page.

1. `shadow` must be false and `card_enabled` true. Watch mode records sentences and shows none.
2. The facts sheet: an engage with no sentence, or a sentence the sheet cannot back, places nothing. Read the moment; if `proposed` is present and `delivery` says withheld, the sheet is missing the fact.
3. The card snippet: it starts polling 12 seconds after the visitor id is known and only while the tab is visible. A test that navigates away in 10 seconds never collects the card.
4. The holdout: one visitor in five on a new site is held back on purpose. Test with several visitors, not one.
5. A visitor who bought in the last 24 hours, or who is in checkout, hears nothing by design.

## The wrong sentence showed

The sheet is the source of every sentence, so a wrong sentence is a wrong or stale fact: an old free shipping line, a code that expired, a size note on the wrong handle, a zone whose countries are wrong. Read the sheet back with `GET /v1/sdk/{id}/facts` and fix it there. If the sentence is right for the sheet and wrong for the visitor (the home zone's line said to a visitor abroad), add the zone for their country; a visitor whose country matches no zone hears nothing about shipping.

## Visitors are spoken to but nothing is credited

The store view shows `shoppers_helped` rising and `orders_credited` at zero.

* Orders must reach NextIntent from your server with the visitor id on them, within seven days of the moment. Without an order feed nothing can be credited. See [Commerce endpoints](/api/commerce-endpoints).
* The `shown` acknowledgement: a card that was placed but never acknowledged does not count as spoken to. If you render your own card from the event, send the ack.
* The visitor id on the order must be the SDK's id, carried through your checkout (the cart beacon stamps it on the cart; your order feed passes it along).

## The store view is all sample rows

`sample: true` with a `needs` list. The site has forwarded no orders yet. Everything in `daily` and Moments is real; the money block fills in with the first order.

## An API call answers 404 or 403

* `404` on a site id you can see in a page: the site belongs to another account, or the key is bound to a different site. A bound key cannot list sites.
* `403 read_only`: a viewer key making a write. Mint an admin key.
* `403 insufficient_scope`: the key's scopes do not include the one the route needs; the answer names it.
* `401`: the key was revoked or expired, or the header is missing `Bearer `.
* `429`: over 600 requests a minute for the key; back off for the `Retry-After` seconds.

## Related

* [Create a site and install the SDK](/website/create-a-site)
* [Watch mode and active mode](/website/modes)
* [API keys](/website/api-keys)
* [Troubleshooting for Shopify](/shopify/troubleshooting)
