docusaurus build "Error: Duplicate route" sidebar path
Fixes Docusaurus builds failing with a duplicate route error from colliding page paths. Use when the error names a duplicated route. Not for sidebar file syntax errors.
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
- 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.
- Decide which page keeps the URL. For the other, set an explicit
slugin its front matter or rename the file. Expected: each page now has a distinct route. - 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.
- 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