Docusaurus Troubleshooting Guide

This guide helps developers identify and fix common errors when working with Docusaurus-based documentation sites, particularly focusing on MDX syntax errors, configuration issues, and runtime problems.

Table of Contents

1. MDX Syntax Errors
2. Configuration Errors
3. Runtime Errors
4. Build Errors
5. Quick Reference

---

MDX Syntax Errors

MDX (Markdown + JSX) is stricter than regular Markdown. Here are the most common issues:

Error: Unexpected character before name

Error Message:

Unexpected character `5` (U+0035) before name, expected a character
that can start a name, such as a letter, `$`, or `_`

Cause: Using < or > characters followed by numbers in text. MDX interprets these as HTML/JSX tags.

Examples of Problematic Text:

- Response time <500ms
- Load time <2 seconds
- Score >95%
- Cost <$15

Solution: Escape the characters using HTML entities:

✅ CORRECT:
- Response time <500ms
- Load time <2 seconds
- Score >95%
- Cost <$15

Quick Find & Replace:

1. Open your MDX/MD file
2. Search for patterns: <[0-9] and >[0-9]
3. Replace < with < and > with >

Example Fix:

BEFORE:
- [ ] Media loading time <500ms globally
- [ ] Content standards compliance >95%

AFTER:
- [ ] Media loading time &lt;500ms globally
- [ ] Content standards compliance &gt;95%

---

Error: Unexpected closing tag

Error Message:

Unexpected closing tag `</video>`, expected corresponding closing
tag for `<source>` (25:3-25:140)

Cause: Self-closing HTML tags (like <source>, <img>, <br>, <input>) must use JSX syntax in MDX.

Examples of Problematic HTML:

❌ WRONG:
<video controls>
  <source src="video.mp4" type="video/mp4">
  Your browser does not support video.
</video>

<img src="logo.png" alt="Logo">
<br>
<input type="text" name="search">

Solution: Add self-closing slash />

✅ CORRECT:
<video controls>
  <source src="video.mp4" type="video/mp4" />
  Your browser does not support video.
</video>

<img src="logo.png" alt="Logo" />
<br />
<input type="text" name="search" />

Tags that require self-closing in MDX:

• <img>
• <br>
• <hr>
• <input>
• <source>
• <meta>
• <link>
• <area>
• <base>
• <col>
• <embed>
• <param>
• <track>
• <wbr>

---

Error: Unexpected end of file in name

Error Message:

Unexpected end of file in name, expected a name character such as
letters, digits, `$`, or `_`; whitespace before attributes; or the
end of the tag

Cause: Incomplete or malformed JSX/HTML tags, often due to special characters.

Common Scenarios:

❌ WRONG:
- Cost <$15/month
- Temperature >100°F
- Rating <3.5 stars

✅ CORRECT:
- Cost &lt;$15/month
- Temperature &gt;100°F
- Rating &lt;3.5 stars

---

Configuration Errors

Error: Can't find sidebar with id

Error Message:

Can't find any sidebar with id "standardsSidebar" in version current".
Available sidebar ids are:
- docsSidebar

Cause: Navbar or other components reference sidebar IDs that don't exist in sidebars.config.js.

Location: docusaurus.config.js

How to Fix:

1. Check your sidebars.config.js:

// sidebars.config.js
const sidebars = {
  docsSidebar: [...],  // ✅ This exists
  // standardsSidebar is NOT defined ❌
};

2. Check your docusaurus.config.js navbar:

// docusaurus.config.js
navbar: {
  items: [
    {
      type: 'docSidebar',
      sidebarId: 'docsSidebar',  // ✅ Must match sidebar name
      label: 'Documentation',
    },
    {
      type: 'docSidebar',
      sidebarId: 'standardsSidebar',  // ❌ Doesn't exist!
      label: 'Standards',
    },
  ],
}

3. Fix: Either create the missing sidebar or remove the navbar item:

Option A: Remove the navbar item

navbar: {
  items: [
    {
      type: 'docSidebar',
      sidebarId: 'docsSidebar',
      label: 'Documentation',
    },
    // Removed standardsSidebar reference
  ],
}

Option B: Create the sidebar

// sidebars.config.js
const sidebars = {
  docsSidebar: [...],
  standardsSidebar: [  // Add new sidebar
    'standards/introduction',
    'standards/coding-standards',
  ],
};

---

Error: Module not found - custom.css

Error Message:

Module not found: Error: Can't resolve
'C:\path\to\src\css\custom.css'

Cause: The docusaurus.config.js references a CSS file that doesn't exist.

Location: src/css/custom.css

How to Fix:

1. Create the directory:

mkdir -p src/css

2. Create the file src/css/custom.css:

/**
 * Custom CSS for Docusaurus site
 */

/* Brand Colors */
:root {
  --ifm-color-primary: #0066cc;
  --ifm-color-primary-dark: #005cb8;
  --ifm-color-primary-darker: #0057ad;
  --ifm-color-primary-darkest: #00478f;
  --ifm-color-primary-light: #0070e0;
  --ifm-color-primary-lighter: #0075eb;
  --ifm-color-primary-lightest: #1a85ff;
  --ifm-code-font-size: 95%;
}

/* Dark mode colors */
[data-theme='dark'] {
  --ifm-color-primary: #1a85ff;
  --ifm-color-primary-dark: #0070e0;
  --ifm-color-primary-darker: #006ad4;
  --ifm-color-primary-darkest: #0057ad;
  --ifm-color-primary-light: #3399ff;
  --ifm-color-primary-lighter: #4da3ff;
  --ifm-color-primary-lightest: #66b3ff;
}

/* Video responsive styling */
video {
  max-width: 100%;
  height: auto;
}

---

Runtime Errors

Error: process is not defined

Error Message:

ReferenceError: process is not defined
    at eval (webpack-internal:///./src/component/firebase_init.js:12:30)

Cause: Accessing process.env in browser-side code without proper checks.

Location: Any JavaScript/JSX file that accesses environment variables

How to Fix:

Add runtime checks before accessing process.env:

❌ WRONG:
const firebaseConfig = {
  apiKey: process.env.REACT_APP_FIREBASE_API_KEY,
  authDomain: process.env.REACT_APP_FIREBASE_AUTH_DOMAIN,
};

✅ CORRECT:
const firebaseConfig = {
  apiKey: typeof process !== 'undefined' && process.env?.REACT_APP_FIREBASE_API_KEY || "default-value",
  authDomain: typeof process !== 'undefined' && process.env?.REACT_APP_FIREBASE_AUTH_DOMAIN || "default-value",
};

Alternative using try-catch:

let apiKey = "default-value";
try {
  apiKey = process.env.REACT_APP_FIREBASE_API_KEY || apiKey;
} catch (e) {
  // process not available in browser
}

const firebaseConfig = {
  apiKey: apiKey,
};

---

Error: Broken Markdown links

Warning Message:

[WARNING] Markdown link with URL `../guides/docusaurus-setup.md`
couldn't be resolved.

Cause: Link points to a file that doesn't exist.

How to Fix:

Option 1: Remove the link

❌ BEFORE:
## Related Documents
- [Docusaurus Setup](../guides/docusaurus-setup.md)
- [Firebase Auth](../guides/firebase-auth.md)

✅ AFTER:
## Related Documents
<!-- Coming soon:
- Docusaurus Setup Guide
- Firebase Authentication Guide
-->

Option 2: Create the missing file

mkdir -p docs/guides
touch docs/guides/docusaurus-setup.md

Then add proper frontmatter:

---
title: Docusaurus Setup Guide
version: 1.0
author: Your Name
last_updated: 2025-09-29
category: Guides
tags: [docusaurus, setup, guide]
---

# Docusaurus Setup Guide

Content here...

Option 3: Fix the link path

✅ CORRECT PATH:
- [Architecture](./system-architecture.md)
- [Implementation Plan](../../project-management/implementation-plan.md)

---

Build Errors

Error: Cannot find module

Error Message:

Error: Cannot find module '@docusaurus/plugin-content-docs'

Cause: Missing dependencies

How to Fix:

# Clear cache and reinstall
npm run clear
rm -rf node_modules package-lock.json
npm install

# Or just install missing package
npm install @docusaurus/plugin-content-docs

---

Error: Port already in use

Error Message:

[ERROR] Something is already running on port 3000.

How to Fix:

Option 1: Kill the process

# On Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# On macOS/Linux
lsof -ti:3000 | xargs kill -9

Option 2: Use a different port

PORT=3001 npm start
# or
PORT=3002 npm start

---

Quick Reference

Common MDX Fixes Cheat Sheet

Problem	Wrong ❌	Correct ✅
Less than with number	<500ms	&lt;500ms
Greater than with number	>95%	&gt;95%
Dollar sign after less than	<$15	&lt;$15
Self-closing img tag	<img src="x">	<img src="x" />
Self-closing source tag	<source src="x">	<source src="x" />
Self-closing br tag	<br>	<br />
Self-closing input tag	<input type="text">	<input type="text" />

HTML Entity Reference

Character	Entity	Description
<	&lt;	Less than
>	&gt;	Greater than
&	&amp;	Ampersand
"	&quot;	Double quote
'	&apos; or &#39;	Single quote
	&nbsp;	Non-breaking space

Testing Your Changes

1. Clear the cache:

npm run clear

2. Start development server:

npm start
# or with specific port
PORT=3002 npm start

3. Build for production:

npm run build

4. Serve production build:

npm run serve

5. Run linting:

npm run lint

---

Debugging Tips

Enable Verbose Logging

# Run with debug output
DEBUG=* npm start

# Or just Docusaurus debug
DEBUG=docusaurus:* npm start

Check Browser Console

1. Open browser DevTools (F12)
2. Check Console tab for JavaScript errors
3. Check Network tab for failed requests
4. Check Sources tab to debug JavaScript

Common Development Workflow

# 1. Clear cache when switching branches or after config changes
npm run clear

# 2. Start dev server
npm start

# 3. If errors, check:
#    - Browser console
#    - Terminal output
#    - This troubleshooting guide

# 4. Make fixes

# 5. Test build before committing
npm run build
npm run serve

---

Getting Help

If you encounter an error not covered in this guide:

1. Check the error message carefully - it usually tells you the file and line number
2. Search the Docusaurus documentation: https://docusaurus.io/docs
3. Check the GitHub issues: https://github.com/facebook/docusaurus/issues
4. Ask the team - someone else may have encountered the same issue

---

Related Documentation

• Content Publishing Guide
• Publishing Quick Reference
• System Architecture
• Docusaurus Official Docs
• MDX Documentation

---

Last Updated: 2025-09-29 Maintained By: Symphony Core Systems Team