docusaurus "Error: Invalid sidebar file" config
Fixes Docusaurus builds failing with an invalid sidebar file error. Use when the error names your sidebars file. Not for duplicate routes or versioning errors.
TL;DR
Fix the sidebar file's JavaScript syntax or its shape: it must export an object mapping sidebar IDs to arrays of items, and every doc ID it names must exist.
Error
Error: Invalid sidebar file at "sidebars.js".Steps
- Check the file parses:
node -e "require('./sidebars.js')"and read the thrown error. Expected: a syntax error with a line number, or a successful load. - Verify the shape: the default export is an object like
{tutorialSidebar: [...]}where each item is a doc ID string, a category object, or a link object. Expected: no bare strings where objects are required and vice versa. - Confirm every doc ID in the sidebar matches an actual doc (file name without extension, or explicit id in front matter). Expected: no sidebar entry points at a deleted or renamed doc.
- Rebuild with
npm run build. Expected: the sidebar loads and the build proceeds.
When to use
- The build fails naming sidebars.js (or sidebars.ts) as invalid
- The sidebar was hand-edited or generated by a docs agent
- Docs were renamed without updating the sidebar
When not to use
- The sidebar loads but a page 404s (a routing issue instead)
- The error is a duplicate route (fix the slug collision)
- You use autogenerated sidebars (check the docs folder structure instead)
Tool compatibility
Docusaurus 2.x and 3.x. sidebars.ts is supported in 3.x with the same shape rules.
Variant phrasings
invalid sidebar after converting to TypeScript
The TS sidebar must still default-export the sidebar object. A named export alone fails validation.
sidebar references docs from a versioned folder
Versioned sidebars live in versioned_sidebars; the current sidebars.js must only reference current docs.
Why it happens
The sidebar file is executable config, so both JS syntax errors and semantic errors (unknown doc IDs, wrong item shapes) surface as "invalid sidebar". Generated sidebars are the usual source: agents emit plausible-looking structures that do not match the real doc IDs.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_5Ocy6BA8N4aXH7ZV9rUhtQ