> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/tutorials/developer/troubleshooting.md).

# Troubleshooting

Common errors when embedding Fastn, with their causes and fixes.

### Blank embed / iframe renders nothing

**Most likely cause:** an expired or hardcoded token.

Embed tokens expire after 15 minutes. If a token is hardcoded into your frontend or cached and reused, it works until it expires, then the iframe loads blank with no obvious error.

**Fix:** Generate a fresh token from your backend on each page load. Never hardcode or cache tokens. See [Generating Embed Tokens](/tutorials/developer/generating-embed-tokens.md).

**Also check:** In production, confirm `FASTN_API_KEY` is bound on the runtime, not just present in CI. An undefined API key means token generation fails silently. See [Deployment](/tutorials/developer/deployment.md).

### 404 on the token request

**Most likely cause:** the wrong org identifier.

`endOrgId` must be the customer's internal UUID. The customer slug and the External ID both return 404.

### Requests fail with a test key

**Most likely cause:** the missing test-mode header.

Requests made with a `fsk_test_` key require the header `X-fastn-Test-Mode: true`. Without it, requests fail in ways the error message doesn't make obvious.

**Fix:** Add `X-fastn-Test-Mode: true` for test keys. Remove it for live keys. See [Authentication & API Keys](https://claude.ai/fastn/tutorials/developer/authentication-and-api-keys).

### "Failed to fetch" in the widget

**Most likely cause:** a tenancy or token mismatch.

This can appear when the iframe URL's tenancy shape doesn't match how the token was minted — for example, a single-tenant embed where the `tenant-id` and token identity don't line up.

**Fix:** Confirm the iframe URL matches your intended tenancy (see [Tenancy](/tutorials/developer/understanding-tenancy.md)), and that the token was generated with the correct `endOrgId` and identity fields. Confirm the backend token pattern is being used rather than a hardcoded token.

### Empty response token

**Most likely cause:** reading the token from the wrong place in the response.

The token is nested under `data` in the response — `response.data.token`, not `response.token`.

**Fix:** Read `json.data.token`. See [Generating Embed Tokens](/tutorials/developer/generating-embed-tokens.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fastn.ai/tutorials/developer/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.