# Troubleshooting

> **Related:** [Project access](https://docs.atmyapp.com/account.md) · [Hand the website over to your client](https://docs.atmyapp.com/ai-assistant.md) · [Changelog](https://docs.atmyapp.com/changelog.md) · [Deploy your website](https://docs.atmyapp.com/deployment.md) · [Examples](https://docs.atmyapp.com/examples.md) · [Choose your integration](https://docs.atmyapp.com/integrations.md) · [Connect a JavaScript website](https://docs.atmyapp.com/quick-start.md)
> **Also:** [HTML version](https://docs.atmyapp.com/troubleshooting) · [Docs index](https://docs.atmyapp.com/llms.txt)

---
Start with a known document and the exact project URL. Turn on `errorPolicy: 'throw'` while investigating storage or collection reads; the Core default can return empty values or placeholders on failure.

| Symptom                          | Check                                                       | Next action                                                          |
| -------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| API key rejected                 | Website key belongs to the selected project/environment     | Replace the key; do not substitute a CLI token                       |
| Requests go to the wrong route   | `baseUrl` includes the full project API path                | Copy the URL from project configuration                              |
| Document missing                 | Stored path, schema definition, and published content agree | Create/publish the content; migration alone does not fill every file |
| `getValue` unavailable           | A runtime schema was passed to `createAtMyAppClient`        | Pass `schema`, not just a TypeScript generic                         |
| Collection appears empty         | Error policy, filters, locale, and preview selection        | Try an unfiltered known collection with errors enabled               |
| Static website shows old content | New content build was deployed                              | Inspect the build and hosting workflow                               |
| Preview shows published content  | Dynamic rendering and per-request preview key               | Inspect the query, runtime mode, and cache policy                    |
| Preview expired                  | Capability validity                                         | Reopen the preview; avoid published-content fallback                 |
| Astro metadata missing           | Astro preset and `website.metadata` configuration           | Enable the preset and read the metadata guide                        |
| Form is unavailable              | Submission open state and CAPTCHA requirements              | Check type status and widget configuration                           |
| Upload fails                     | File field names, encoding, and submission configuration    | Use SDK-generated form parameters and multipart for files            |

## Schema and CLI failures

Run the CLI from the connected workspace. Confirm `.ama/session.json` exists, check the selected project, and use `atmyapp migrate --dry-run --verbose`. Use a canonical `atmyapp.schema.ts` (or supported JS/JSON equivalent) and inspect the reported field path. [Field options](/reference/fields/) documents constraints such as immutable slugs and localized array identities.

## Diagnostics

[Optional diagnostics](/guides/diagnostics/) helps compare SDK versions, build metadata, connectivity, and preview state. A static report describes build time; its timestamp is not a continuously running health check. A successful connection report does not prove every content path or submission works.

## Search in these docs

Search uses a generated Pagefind index. In a local `astro dev` session, Starlight shows a development notice instead of search results. Build the docs and run `astro preview` to test real search. The deployed output must include the `pagefind` directory and `_astro` assets.

If deployed search fails, check the browser network panel for missing Pagefind assets and confirm the HTML and search index were deployed together. You can also use the sidebar's complete guide and reference index.

## Ask for help

Send the affected page, the operation you tried, and a sanitized error or diagnostics report to [support](mailto:contact@atmyapp.com). Include whether it happens locally, during a build, or on the deployed site. Do not include CLI tokens or raw preview keys.