Troubleshooting

Each entry starts with the message as Nimbus or your tools print it. Search this page for a phrase from your error.

GitHub rate-limited the template download (HTTP 403)

GitHub rate-limited the template download (HTTP 403).

The scaffolder, nimbus-docs outdated and diff download starter files from GitHub, which allows 60 anonymous requests an hour from one address. Shared networks and CI hit that quickly. Set GIGET_AUTH to a GitHub token for the run:

GIGET_AUTH=<your-github-token> npm create @cloudflare/nimbus-docs@latest

The token needs no scopes. To work without the network, pass --template-dir <path> with a local copy of the templates.

Unknown frontmatter key “…”

lastVerified: Unknown frontmatter key "lastVerified".

A page’s frontmatter has a key the docs schema doesn’t know. Either remove it, or declare it in src/content.config.ts with schemaFields:

docs: defineCollection(
  docsCollection({
    schemaFields: { lastVerified: z.coerce.date().optional() },
  }),
),

Pages created from the content-* registry recipes can include lastVerified; declare it as above, or delete the line. Frontmatter lists every key the schema already knows.

Unknown MDX component tag

[nimbus-docs] Unknown MDX component tag:
  src/content/docs/guide.mdx:12:1  <Callout />  →  Register it in src/components.ts, or add an explicit `import` at the top of this file.

MDX only renders a component it knows about. Add it to src/components.ts to use it on every page, or import it at the top of the page. A component from the registry needs installing first, with nimbus-docs add <slug>; see Add components and features.

Search could not load

Search could not load. Check your connection and reload the page. If it persists, ask the site owner to rebuild and deploy the search index.

The search index is written at the end of the production build, into dist/pagefind/. If it’s missing from the deployed site, check that the build finished and that the whole of dist/ was uploaded. In astro dev, search says “Search is available after a production build.”; run the build and astro preview to try it. See Search.

A page 404s with or without a trailing slash

With trailingSlash: "always" or "never" in astro.config.ts, astro dev answers only the matching form of each URL, and links Nimbus generates use that form. A hand-written link in the other form 404s in dev, and on some hosts in production. Match the setting, or leave trailingSlash at its default. Links and trailing slashes covers each setting.

This is a shallow clone, so pages get no git dates

this is a shallow clone, so pages get no git dates (sitemap lastmod, "Last updated"). Run git fetch --unshallow, or set fetch-depth: 0 in CI, to restore them.

The “Last updated” line and the sitemap’s dates come from git history, and CI usually clones only the latest commit. Set fetch-depth: 0 on the checkout step, or run git fetch --unshallow before the build.

Ignored build scripts: esbuild, sharp

pnpm 10 asks before running a dependency’s install scripts. The scaffolder’s pnpm-workspace.yaml already declines them for esbuild and sharp, and for workerd on Cloudflare, because each ships a working prebuilt binary. The warning is safe to ignore, and approving them with pnpm approve-builds is also fine.

Still stuck?

Ask in GitHub Discussions, or open an issue if it looks like a bug. Include:

• the versions of @cloudflare/nimbus-docs and astro from your lockfile, and of Node (node --version),
• the full error, copied as text,
• the command you ran, and your package manager,
• what you expected to happen.