It's not working

Find what you see below. Each section says why it happens, how to fix it, and how to confirm the fix. Start with the Is it working? check in Settings › Channels: keep it open while you load your site in another tab.

#What the check can and can't see

The check reports only what reaches the Telltale server:

• The script was fetched. When a page loads sdk/v1.js, the server notes the page's address, if the browser sends it (most do). This is the Script loaded on step.
• A session started. The SDK started on an allowed page with a valid key. This is First session received once its first events arrive.
• A request was refused. The page address is not on your Site's list, or the key belongs to no Site. The check says which.
• A user was linked. A session has a signed-in user or account. This is Signed-in user linked.

It cannot see what happens only inside the browser. A Content Security Policy block, a held tag waiting for consent, or an ad blocker all look the same from the server: the script loaded (or not even that) and no session started. When the check shows "script loaded" but nothing after it, it is telling you to look in the browser. Open DevTools on your site and check the Console and Network tabs.

#Nothing arrives at all

What you see. The check stays at its first step. No Script loaded on line appears.

Why. The page never asked for the script. Usually the tag is not on the page you opened: it was saved but not published, it is in the wrong file or theme, a cache still serves the old page, or a blocker stopped the request.

Fix.

1. Open your site, right-click, choose View Page Source, and search for sdk/v1.js. If it is missing, go back to your platform's install page: Next.js, React, WordPress, Shopify, Webflow, Google Tag Manager.
2. If it is there, open DevTools › Network, reload, and filter for sdk. A request marked blocked usually means an extension or a Content Security Policy (see below).
3. Publish (Webflow, GTM), clear your cache (WordPress), or edit the published theme (Shopify).

Confirm. View Page Source shows the tag, and DevTools › Network shows sdk/v1.js with status 200.

#The page address isn't on the allowed list

What you see. The check says requests were refused because the page address is not on the Site's list, and names that address. Or it says the script loaded on a nearby address, such as the www version of your domain. In DevTools › Network, api/sdk/init answers 403 ("Site key or origin not allowed"). The Console may also report it as a CORS error, because a refused request gets no CORS header.

Why. Your key only works on the addresses you listed for the Site. The match is exact: scheme, host and port. https://www.example.com, https://example.com, http://example.com and https://example.com:8443 are four different addresses. Staging domains, myshopify.com and webflow.io addresses, and preview deployments are different too.

Fix. Go to Settings › Channels › Website addresses and add every address visitors use, exactly as it appears in the browser's address bar (up to the first /). For staging or localhost, a separate Site keeps test traffic out of your real numbers.

Confirm. Reload the page. api/sdk/init answers 200 and the check shows First session received.

#The key is wrong or was changed

What you see. The check says requests came in with a key no Site has. Or DevTools › Network shows api/sdk/init answering 403 ("Site key or origin not allowed"), often also reported in the Console as a CORS error, while the page address is on your list.

Why. The tag's data-telltale-key does not match a current publishable key: a typo, a copy from another Site or workspace, a key that was rotated, or the server key (ao_sk_...) pasted by mistake.

Fix. Copy the tag again from Settings › Channels, which has the current key filled in, and replace the whole tag. The browser always uses the publishable key (ao_pk_...). If the server key was ever on a page, rotate it (see Authentication and keys).

Confirm. api/sdk/init answers 200 and the check moves to First session received.

#The script waits for consent

What you see. Script loaded on appears, but no session follows. There are no errors in the Console. api/sdk/init never appears in DevTools › Network.

Why. The tag has data-telltale-wait-for-consent (or waitForConsent: true), so it sends nothing until your banner calls optIn(). That is the intended behaviour. Either the banner has not been answered, the visitor refused, or nothing calls optIn().

Fix.

1. Accept measurement in your banner and reload.
2. In the Console, run window.Telltale.getClient().status().consent. held means nobody has called optIn(); withdrawn means optOut() was called or a refusal is saved.
3. Make sure your banner's "allowed" callback calls window.Telltale.getClient().optIn(). See the Consent bridge guide and the recipes for OneTrust, Cookiebot and Sourcepoint.

If your site has no banner, remove data-telltale-wait-for-consent. Do not remove it to get around a banner you do have.

Confirm. After you accept, status().consent is granted and the check shows First session received.

#A Content Security Policy blocks it

What you see. The Console shows a message such as "Refused to load the script" or "Refused to connect" naming the Telltale server. The check shows no session, and may not show Script loaded on either.

Why. Your site's Content Security Policy does not list the Telltale server. A blocked script never loads; a blocked connection loads the script but stops every request.

Fix. Add the Telltale server, https://app.trytelltale.dev, to script-src and to connect-src (and to script-src-elem if your policy has one), or use a nonce with 'strict-dynamic' plus connect-src https://app.trytelltale.dev. Never add 'unsafe-inline' or 'unsafe-eval'. The Content Security Policy guide has both options.

Confirm. Reload with the Console open: no violation names the Telltale server, and the check shows First session received. Two blob: worker reports are expected if you did not allow worker-src blob:; they do not stop collection.

#Sessions arrive but no signed-in user is linked

What you see. First session received is done, but Signed-in user linked never completes.

Why. Nothing has told Telltale who is signed in yet. Either identify is not set up, it runs before your auth knows the user, it runs while the tag is held for consent (it is then ignored), or you tested while signed out.

Fix.

1. Sign in to your own site as a test user, then browse a page.
2. Recommended: link the session from your server after sign-in (Quickstart step 2, Server API › Associate identity).
3. Or in the browser: call window.Telltale.getClient().identify({ userId, accountId }) once your auth knows the user, inside try { ... } catch {}, and again after optIn() on a held tag. Platform examples are on each install page.

Use opaque, stable internal IDs. Never send e-mail addresses, names or phone numbers.

Confirm. The check shows Signed-in user linked, and the session opened from it shows the user and account IDs.

#It works on one page but not others

What you see. Sessions arrive from some pages only.

Why. The tag was added to one page or template instead of the whole site: a Webflow page's settings, a single Next.js page, a Shopify section file, or a WordPress snippet limited to some pages.

Fix. Move the tag to the site-wide place: Webflow Site settings, the Next.js root layout, Shopify's layout/theme.liquid, WordPress's Header box or wp_head, or a GTM trigger on All Pages.

Confirm. View Page Source on a page that was missing it now shows sdk/v1.js.

#It works locally but not on the live site

What you see. It works on localhost or staging, not in production (or the other way round).

Why. Usually each address needs to be on the Site's list (see the allowed list), or the live site has a Content Security Policy, a cache or an optimisation plugin that your local build does not.

Fix. Add the live address under Settings › Channels › Website addresses, clear caches, and exclude sdk/v1.js from script-delaying or combining features. Keep local and staging on a separate Site.

Confirm. The live address appears under Script loaded on and then First session received.

#Ad blockers and privacy extensions

What you see. It works for you in one browser and not another, or for some visitors only. DevTools › Network shows the script request blocked by the client.

Why. Some extensions block third-party scripts. Telltale does not try to get around them: when a visitor's browser blocks it, nothing is collected for that visitor.

Fix. Test in a private window with extensions turned off. Nothing to fix for visitors.

Confirm. The test window produces First session received.

#Shopify checkout pages show nothing

What you see. Sessions show product, cart and account pages, but never checkout, thank you or order status.

Why. Shopify does not run theme code on its checkout pages, so the tag cannot load there. See Install on Shopify › Checkout.

Fix. Nothing to fix. Protect the steps before checkout: account, cart and product pages.

Confirm. Not applicable.

#The dashboard says Unknown

What you see. Sessions arrive, but the verdict is Unknown rather than AI agent or Human.

Why. Unknown means the evidence was not enough to say either way, often because the visit was short or had little interaction. Unknown is not human. Telltale needs evidence from a real device before it says Human. (The public demo shows this as "Monitoring" or "More activity needed".)

Fix. Nothing is broken. Browse for longer, click and type as a visitor would, and the verdict can change. For a protected action, decide what Unknown means in Control › Rules; never treat it as Human.

Confirm. A longer test visit by a person on a physical device usually ends Human; one driven by an automated browser ends AI agent or Unknown. See Verdicts and authorization.

#Telltale for MCP servers: no calls arrive

What you see. Settings › Channels › MCP server › Is it working? still says "Waiting for the first call" after an agent called a tool.

Why. The wrapper sends calls from your server in batches, usually within five seconds. Nothing arrives when the key is wrong (a publishable ao_pk_ key, or a server key that was rotated away: the batch is refused with 401 and dropped), when your server can't reach the Telltale server, or when the server isn't wrapped where the tools are registered.

Fix. Use the Site's server key from Settings › Channels › Server keys, kept in your server's environment. Turn on debug: true (or TELLTALE_DEBUG=1) and read stderr: each batch logs how many calls were accepted, replayed and rejected. A rejected call names its field in the answer's rejected[] list (index, field, error), and the rest of the batch is still recorded; an adapter older than the server is the usual cause, so download it again.

Confirm. Make one tool call from any MCP client and the check turns to "Working" with the time of the last batch. More cases (no accounts, "Not declared" clients, calls counted twice) are in Telltale for MCP servers.

#Telltale for APIs: no calls arrive, or calls are held

What you see. Settings › Channels › API › Is it working? still says "Waiting for the first call", calls are refused, or a protected route answers with a hold.

Why. As with MCP: a wrong key or an unreachable Telltale server stops every batch. A call whose route is a raw path (/v1/invoices/12345 instead of /v1/invoices/:id) is refused alone and listed in rejected[]. A route you protect asks your rule (Control › Rules) before the handler runs; with no saved rule an AI agent call is held for review by default, and Unknown is allowed.

Fix. Check the server key and turn on debug: true. Return route templates (or let the built-in normaliser do it). For held calls, approve them in Control › Approvals › Waiting, or settle them with your own check through the step-up endpoint; save a rule for the route if the default isn't what you want.

Confirm. One request to your API turns the check to "Working". More cases are in Telltale for APIs.

#Still stuck

Collect what DevTools shows for sdk/v1.js and api/sdk/init (status code and response), and any Console messages that name the Telltale server, and email them to jad@heypharos.com. Never send your server key or a session token.