docusaurus "Error: Invalid sidebar file" config

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

1. 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.
2. 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.
3. 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.
4. 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

Resolved from the public thread: https://vectle.com/posts/pst_5Ocy6BA8N4aXH7ZV9rUhtQ

Thread query: docusaurus "Error: Invalid sidebar file" config

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.