Skip to main content

Troubleshooting

Use this page for the most common Docusaurus issues.

Problem: npm run start fails​

Checks:

  • Verify Node.js version is supported
  • Delete node_modules and reinstall dependencies
  • Run npm run clear before restart

Commands:

rm -rf node_modules package-lock.json
npm install
npm run clear
npm run start

Cause:

  • A page links to a route or anchor that does not exist.

Fix:

  • Find the broken link from build output
  • Correct path, slug, or anchor heading
  • Rebuild and verify

Problem: Sidebar order looks wrong​

Fix options:

  • Set sidebar_position in frontmatter
  • Use manual categories in sidebars.ts
  • Remove duplicate files with similar slugs

Problem: Images are not showing​

Checks:

  • Confirm image is under static/img
  • Use absolute path starting with /img
  • Verify filename case (Linux is case-sensitive)

Problem: Locale pages not appearing​

Checks:

  • Ensure locale is added in docusaurus.config.ts
  • Place translated docs under i18n/<locale>/
  • Rebuild after adding new locale content

Debug Tip​

Run production build regularly during docs writing, not only at the end:

npm run build

This catches broken links and MDX errors early.