Docusaurus "Docusaurus found broken links" build failure in CI

By Daniel Zoghalchali·Latchkey

During docusaurus build, link checking runs with onBrokenLinks: "throw" by default, so any internal link that does not resolve to a real page fails the build and lists the offending links.

What this error means

docusaurus build aborts with "Error: Docusaurus found broken links!" and a list of source pages and the broken link targets they contain.

[ERROR] Error: Docusaurus found broken links!

Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
- Broken link on source page path = /docs/intro:
   -> linking to /docs/setup (resolved as: /docs/setup)

Common causes

A link points to a non-existent path

The target page was renamed, moved, or never existed at that route, so link validation cannot resolve it.

A wrong absolute or relative path

An absolute link that omits the docs base path, or a relative link with the wrong depth, resolves to a missing route.

How to fix it

Fix the broken links it lists

1. Read the source page and target path printed under each broken link.
2. Correct the link to the real route, or restore the missing page.
3. Re-run docusaurus build to confirm zero broken links.

npm run build

Use doc IDs or relative .md links

Linking by relative Markdown file path lets Docusaurus validate and rewrite links to the correct route.

[Setup](./setup.md)

How to prevent it

• Link by relative .md path so links are validated at build.
• Run docusaurus build in CI to catch broken links before deploy.
• Update links when you rename or move docs.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation