10. Troubleshooting

Welcome to the troubleshooting section. Here you will find guides for common issues encountered when using Docusaurus in our Docker environment.

Available Guides

• 502 Bad Gateway Errors: Why the site might be down after a restart and how to fix it.
• New Folders Not Updating: What to do when newly created documentation folders don't appear on the front end.
• Sidebar & Menu Management: How to hide or remove unwanted items from the navigation.
• YAML Syntax & Broken Links: Fixing 502 errors caused by frontmatter errors and broken internal links.
• Google Ads Docs 502 (YAML Frontmatter): Incident log and fix for YAML frontmatter colons breaking the build.
• Mermaid Plugin Integration: Solving connection issues and build lag after installing Mermaid.
• Undefined Components (MDX): Fixing build errors caused by missing component imports or definitions.
• Case Study: Badge Component Error: A detailed log of the 502 error caused by an undefined Badge component.
• Broken Media Paths: Fixing build failures caused by absolute image/video paths.
• Cloudflare Tunnel 502 Recovery (brain.id86.net): Incident log and exact recovery steps used to restore service.
• Post-Restart 502 (Build Window): Why 502 appears right after restart and the fast recovery command that restores service.
• GSheet Post-Restart 502 Recovery: Incident report for Google Sheet migration rollout, root cause, and exact fix steps.
• Server Onboarding Runtime and Performance Incident: Full post-incident report covering chunk errors, MDX failures, search plugin runtime crash, and high CPU/RAM recovery.
• Linux Server Docs Build Failures (2026-03-01): Six build error categories from the linux-server batch rewrite — inverted frontmatter, unquoted colons, TabItem/list conflicts, bare angle brackets, missing imports, and Prism language config.
• brain.id86.net Wrong Container Recovery: Incident report for the linux-server route showing dummy content because Cloudflare Tunnel pointed the production hostname to docusaurus-brain2 instead of docusaurus.

---

Quick Reference Commands

If the site is not responding, try these commands first:

# Watch build progress
sudo docker logs -f docusaurus

# Restart the service
sudo docker restart docusaurus

# Clear cache and restart (Nuclear Option)
sudo docker exec docusaurus rm -rf /app/build /app/.docusaurus
sudo docker restart docusaurus