Skip to main content

​
Docs Troubleshooting

​
Quick Checks

pnpm check:docs
pnpm docs:linkcheck
pnpm docs:validate
Run checks from the repository root unless the command explicitly changes into docs.

​
Common Issues

Symptom: page exists but does not appear in docs sidebar/tab structure.Fix: Add the page route to docs/docs.json and re-run pnpm docs:validate to confirm structure integrity.
Symptom: pnpm check:docs fails on format or heading rules.Fix: Follow linter output line-by-line, keep heading hierarchy and list formatting consistent, and prefer native Mintlify components over custom HTML blocks.
Symptom: pnpm docs:validate fails despite passing markdown lint.Fix: Check docs/docs.json tab/group/page mapping, confirm every routed page exists under docs/, and ensure each page exposes a title frontmatter field or top-level heading.
Symptom: the route exists, but Mintlify shows Page not found! and an unexpected error page.Fix: Reduce the page to standard Mintlify frontmatter (title, summary) plus supported Markdown or Mintlify components, then run pnpm docs:routecheck --base-url <preview-or-site-url> so you validate real route rendering instead of static checks only.

​
PR Checklist

1

Validate formatting and links

Run pnpm check:docs and pnpm docs:linkcheck.
2

Validate Mintlify routing and structure

Run pnpm docs:validate.
3

Smoke test real route rendering when debugging 500s

Run pnpm docs:routecheck --base-url http://localhost:3000 against a local preview, or point it at the deployed docs host.
4

Spot check key navigation paths

Confirm Docs Portal, FAQ, and Business of Agents are reachable.