Diagram Troubleshooting

Common issues and solutions when working with Mermaid diagrams in ChapterWise.

Syntax Errors

Problem: Diagram shows a red error message instead of rendering.

Solution: Check your Mermaid syntax. Use the Mermaid Live Editor to test and debug your diagram code before adding it to your codex file.

Common syntax mistakes: - Missing diagram type keyword (graph, sequenceDiagram, etc.) - Incorrect arrow syntax (--> not -> for flowcharts) - Unmatched brackets or quotes - Invalid node IDs (avoid special characters)

Loading Spinner Stuck

Problem: The diagram shows "Rendering diagram..." indefinitely.

Solutions: 1. Check browser console for JavaScript errors 2. Ensure Mermaid.js loaded correctly (check network tab) 3. Verify the data-diagram-source attribute isn't empty 4. Try refreshing the page

Dark Mode Issues

Problem: Diagram colors look wrong after switching themes.

Solution: Diagrams automatically re-render when the theme changes. If colors still look wrong: 1. Refresh the page after switching themes 2. Avoid hardcoding colors in your Mermaid syntax — let the theme handle colors

Diagram Too Small

Problem: Diagram appears tiny or compressed.

Solutions: - Use width: 1/1 for complex diagrams - On mobile, diagrams scroll horizontally — this is expected behavior - Simplify the diagram or split into multiple smaller ones

YAML Indentation

Problem: Diagram source gets mangled or includes extra whitespace.

Solution: Always use the YAML literal block scalar (|) for multiline diagram content:

# Correct - literal block scalar preserves formatting
value: |
  graph LR
    A --> B
    B --> C

# Wrong - will break the diagram
value: "graph LR\n  A --> B"

The | character tells YAML to preserve newlines and indentation exactly as written. The content should be indented under the value: key.

Special Characters

Problem: Quotes, parentheses, or other characters cause parse errors.

Solution: Wrap node labels in double quotes:

graph LR
  A["Node with (parentheses)"] --> B["Node with 'quotes'"]

Include File Not Found

Problem: External .mermaid file doesn't load.

Solutions: 1. Check the file path — paths starting with / are relative to project root 2. Verify the file extension is .mermaid or .mmd 3. Ensure the file exists in your project directory 4. Check the browser console for error messages

Diagram Not Rendering in Exports

Note: Mermaid diagrams render client-side with JavaScript. In static exports (PDF, DOCX), diagrams will show the raw Mermaid source code. For static exports, consider generating diagram images separately.

Getting Help