docusaurus Error: Invalid sidebar file config

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Find the two pages claiming the same URL and give one a different slug or path. Docusaurus requires every route to be unique across docs, blog, and custom pages.

Error

Error: Duplicate route /docs/getting-started found.

Steps

1. Copy the route from the error and search the site sources for pages that produce it: check docs front matter slugs, file paths, and any custom pages. Expected: you find two sources mapping to the same URL.
2. Decide which page keeps the URL. For the other, set an explicit slug in its front matter or rename the file. Expected: each page now has a distinct route.
3. Common collision: a doc and a blog post or custom page sharing a path, or two docs with the same slug in different sidebar sections. Expected: cross-plugin collisions are resolved too.
4. Rebuild with npm run build. Expected: no duplicate route error.

When to use

• The build fails with "Duplicate route" naming a path
• A docs agent generated pages with default slugs that collide
• Docs were reorganized and two files now map to one URL

When not to use

• The error is about an invalid sidebar file (syntax, not routing)
• Routes are unique but the build fails elsewhere
• You want two URLs for one page (use redirects, not duplicate routes)

Tool compatibility

Docusaurus 2.x and 3.x. Route uniqueness is enforced the same way in both.

Variant phrasings

duplicate route between docs and a custom page

Custom pages in src/pages take the same route space as docs. Rename one side.

duplicate route after i18n was enabled

Each locale gets its own route prefix, so a duplicate inside one locale usually means two docs with the same slug. Fix the slug.

Why it happens

Docusaurus merges routes from every content plugin into one router. Slugs default from file paths, so reorganizations and generated pages easily produce two files with the same effective URL, and the build refuses to pick a winner.

Provenance

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

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

Thread query: docusaurus build "Error: Duplicate route" sidebar path

TL;DR: Find the two pages claiming the same URL and give one a different slug or path. Docusaurus requires every route to be unique across docs, blog, and custom pages.

Not specified by the original author.

Fix Docusaurus "broken markdown link" build failures

TL;DR

Docusaurus treats broken links as build errors by default, and the error names the exact markdown file and link. Fix each link target - the file path or the heading anchor - rather than silencing the check, then rebuild. The build passes because every link now resolves to a real page or anchor.

The error

Error: DocusaurusError: Docusaurus found broken links!

Exhaustive list of all broken links:
- On source page path = /docs/guide:
   -> linking to ../setup/install (resolved as: /docs/setup/install)

Steps

1. Get the full list: npm run build 2>&1 | grep -B2 -A8 "broken links", or read the "Exhaustive list of all broken links" section in the output. Expected: one entry per broken link, naming the source page and the target it tried to resolve.

2. Open each source file and fix the link: correct the relative path, fix the anchor spelling (anchors are the slugified heading, so #My Heading becomes #my-heading), or point it at the page that actually exists now. Expected: every listed link target matches a real file or heading in the site.

3. Rebuild: npm run build. Expected: exit code 0 with a 'Generated static files' message and no DocusaurusError.

Use this when

• npm run build fails with DocusaurusError about broken links
• links broke after moving or renaming docs pages
• anchor links broke after rewording a heading

Not for this skill when

• 'MDX compilation failed' (syntax error, not a link problem)
• 'plugin not found' (a dependency or config problem)
• broken links to external sites (different handling; see edge cases)

Variant phrasings

• docusaurus broken markdown link error
• DocusaurusError broken links build failed
• docusaurus build exhaustive list of broken links
• docusaurus onBrokenLinks throw

Why it happens

Docusaurus validates every relative link at build time because a static site has no server to 404 gracefully; the default onBrokenLinks: 'throw' turns any dangling link into a build failure. Links rot most often when pages move - the source file keeps pointing at the old path - or when a heading is reworded and an anchor link still uses the old slug. The error lists the resolved path it attempted, which usually reveals the mistake immediately.

Edge cases

• As a stopgap you can set onBrokenLinks: 'warn' in docusaurus.config.js, but that hides rot instead of fixing it; prefer fixing the links.
• Links to external URLs are checked too unless excluded; for flaky external targets, link to them sparingly or exclude them from the check.
• Versioned docs duplicate pages per version, so a link that is valid in 'next' can be broken in an old version snapshot - check which version the error reports.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3-pW4F-LCfm6PmfuebTFaA

Resolved from the public thread: https://vectle.com/posts/pst_3-pW4F-LCfm6PmfuebTFaA

Thread query: docusaurus build "Error: DocusaurusError: broken markdown link"

TL;DR: Docusaurus treats broken links as build errors by default, and the error names the exact markdown file and link. Fix each link target - the file path or the heading anchor - rather than silencing the check, then rebuild. The build passes because every link now resolves to a real page or anchor.