Skip to main content

Troubleshooting: 502 Bad Gateway & WP-CLI MDX Errors

Issue Description​

After migrating WP-CLI documentation from Notion, the Docusaurus site (brain.id86.net) became inaccessible, returning a 502 Bad Gateway error.

Symptoms​

  • Site returns 502 Bad Gateway.
  • Cloudflare Tunnel (cloudflared) logs show Unable to reach the origin service... connect: connection refused.
  • Docusaurus container uptime resets frequently (crash loop).
  • Docker logs (docker logs docusaurus) show MDX compilation errors.

Root Cause​

The crash was caused by invalid MDX syntax in the migrated markdown files, which caused the Docusaurus build process to fail and the container to exit/restart repeatedly.

Specific MDX violations found in Notion exports:

  1. Unescaped Angle Brackets: Tags like <plugin> or <file> in text were interpreted as invalid JSX by the MDX parser.
    • Error: Expected a closing tag for <...> before the end of tableData
  2. Pipe Characters in Tables: Pipes | inside table cells (e.g., <slug | zip>) broke the table structure.
    • Error: Unexpected end of file in name... due to broken table parsing.
  3. Double Escaping: An initial fix attempt inappropriately double-escaped pipes (\\|), causing Unexpected character \ errors.

Diagnosis Steps​

  1. Check Container Status:

    sudo docker ps -a
    # Observed container restarting every few seconds

  2. Inspect Logs:

    sudo docker logs docusaurus --tail 50
    # Found "Error: MDX compilation failed" listing specific files and lines

  3. Verify Network:

    sudo docker logs cloudflared
    # Confirmed "connection refused" to 172.20.0.x:3000

Solution​

The solution involved ensuring all angle brackets and pipe characters were correctly escaped or wrapped in code spans to be treated as literals, not syntax.

Python Script: fix_mdx_universal.py​

A robust Python script was created to parse the markdown files character-by-character and apply fixes safely.

Key Logic:

  • Detects angle brackets <...> that are not valid HTML tags.
  • Wraps them in backticks: <placeholder> → <placeholder>.
  • Detects pipes | inside backticked code spans within table rows.
  • Escapes them: | → \|.

Script Usage​

python3 fix_mdx_universal.py

Full Script​

Click to view fix_mdx_universal.py
import os
import re

# Known valid HTML tags to ignore
HTML_TAGS = {
    'br', 'hr', 'img', 'a', 'b', 'i', 'code', 'table', 'tr', 'td', 'th', 'div', 'span', 
    # ... (see full script in repository)
}

def fix_file(filepath):
    # ... (file reading logic)
    
        # Character-by-character parsing to handle nesting
        while i < len(line):
            # ...
            if char == '<':
                 # Check if valid HTML tag
                 # If not, wrap in backticks: `<content>`
                 # ...

Verification​

After running the script and restarting the container:

  1. Build Success: Logs showed Client: Compiled successfully.
  2. Stable Container: Uptime increased beyond 1 minute.
  3. Site Access: curl https://brain.id86.net returned 302 (Cloudflare Access) instead of 502.

Prevention​

For future Notion migrations:

  • Run the fix_mdx_universal.py script immediately after export/reorganization.
  • Check logs immediately if the site fails to load.