# Troubleshooting

> For the complete documentation index, see [llms.txt](https://falconer.com/docs/llms.txt).

What to check when a page, build, link, image, domain, or redirect doesn't behave as expected.


What to check when a page, build, link, image, domain, or redirect doesn't behave as expected.

## A page is missing from the site

| Check | Why |
| --- | --- |
| The page is in **Docs**, not only in **Files** | A file that isn't linked into Docs isn't published. See [Link a file into Docs](https://falconer.com/docs/public-docs/docs-and-files-views.md#link-a-file-into-docs). |
| The page is under **Published**, not **Private documents** | Only the site's section is built. |
| It isn't private | A private page, or a page in a private section, isn't built. Check **Publishing options** and the page's `access`. See [Private and hidden](https://falconer.com/docs/public-docs/navigation-sections.md#private-and-hidden). |
| It isn't hidden | A hidden page is built but left out of the sidebar. Open it by its address, or show it in navigation. |
| It has a title | A document with no title is left out, and its children take its place. |
| You published after the change | Visitors see the live build, not your edits. Build and publish again. See [Build, preview, and publish](https://falconer.com/docs/public-docs/build-and-publish.md). |

## Changes aren't showing

- Edits only reach visitors in a build you publish. Check **Builds** for the build that's live and when it was made.
- Publishing reaches every edge location within about a minute; the site may briefly show the previous build.
- A page you moved or renamed in **Files** has a new address. The old one redirects after the next published build.

## A build failed or is stuck

- A build that hasn't progressed for 30 minutes is marked **Failed** with "Build stopped unexpectedly". Start a new one; one build runs at a time per site.
- **Failed** means the build didn't finish. Start a new one to retry. A page with a problem, such as an OpenAPI page that can't find its document or a diagram that doesn't parse, shows an error in its place instead of failing the build, so a build that keeps failing isn't caused by one page. Contact Falconer with the build number.
- **Indexing** that never reaches **Indexed** keeps search and Ask the docs on the previous build. Click **Index docsite** on the build to run it again. See [Build status](https://falconer.com/docs/public-docs/build-and-publish.md#build-status).

## Issues lists broken links

Each broken link has a reason:

| Reason | Fix |
| --- | --- |
| Page not found | The path matches no page on the site, even after following redirects. Check the file path and extension, and that the target is linked into Docs and not private. |
| Heading not found | The page exists but has no heading with that anchor. Copy the anchor from the heading's link on the site. |
| Document not published | A reference chip points at a Falconer document that isn't a page on this site. Link the document into Docs, or replace the chip with a plain link. |

Links to other websites and to files that aren't Markdown are never reported. See [Links between pages](https://falconer.com/docs/public-docs/write-pages.md#links-between-pages).

## An image isn't showing

- The file has to be in the space's **Files** view. An image on another website is left as a plain URL and loads only if that site allows it.
- The format has to be one the site serves: SVG, PNG, JPEG, GIF, WebP, AVIF, BMP, or ICO.
- The file has to be under 100 MB, or 5 MB for a logo or favicon.
- Check the path from the page to the image, the same way as a link. See [Images and files](https://falconer.com/docs/public-docs/write-pages.md#images-and-files).

## Search or Ask the docs gives old answers

Both read from the index of the published build, and indexing runs after the build. If you published before indexing finished, they answer from the previously indexed build until it completes. Wait for **Indexed** on the live build, or click **Index docsite** on it. See [When results update](https://falconer.com/docs/public-docs/site-search.md#when-results-update).

## A page is on the site but not in search

- `pagefind: false` in its frontmatter leaves it out of site search and Ask the docs.
- A hidden page is left out of search as well.
- Search needs at least two characters.

## The custom domain won't verify

**Subdomain**

- The CNAME has to point directly at `cname.falconer.com` and have propagated. New records can take a few minutes; click **Check now** after waiting.

**Path on your domain**

- The site has to be published before the check can succeed.
- The forwarding rule has to pass the Falconer host name, keep the path, and forward both `/docs` and `/docs/*`. The check message says which part failed: a redirect, a 404, a wrong host header, your own page being served instead of the docs, or an HTTPS problem.
- Don't cache the docs path on your side.

See [Domain status](https://falconer.com/docs/public-docs/custom-domain.md#domain-status) for what each status means.

## A redirect isn't working

- Redirects take effect on the next build you publish.
- Each old path can appear once, and matching ignores letter case and trailing slashes.
- A site can have 1,000 redirects after wildcards are expanded; above that, publishing is refused. Remove or combine rules with wildcards. See [Redirects](https://falconer.com/docs/public-docs/redirects.md).

## Search engines show the password page

That's expected on a password-protected site: crawlers only ever see the password page. To keep the site out of results entirely, turn off **Allow search engines** in [Search and sharing](https://falconer.com/docs/public-docs/customize-your-site.md#search-and-sharing).

## Ask the docs says the limit was reached

The assistant has daily fair-use limits per visitor, per network, and per organization. Questions are refused until the limit resets. See [Plans and limits](https://falconer.com/docs/public-docs/plans-and-limits.md#ask-the-docs).