Skip to main content

Troubleshooting find.mdx Parse Error Causing 502

This report documents a 502 Bad Gateway incident on brain.id86.net caused by a Docusaurus MDX parse failure in find.mdx.

1) Incident Summary​

  • Symptom: brain.id86.net intermittently returned 502.
  • Tunnel evidence: cloudflared logged Unable to reach the origin service ... connect: connection refused to docusaurus:3000.
  • Impact: users could not reach docs until origin recovered.

2) Confirmed Root Cause​

The docusaurus container startup command runs build before serve:

npm run start
# -> docusaurus build && docusaurus serve --host 0.0.0.0 --port 3000

Build repeatedly failed on:

  • File: docs/server/linux-server/02-Navigation-and-Filesystem/Search/find.mdx
  • Location: line 53, column 44
  • Error: Unexpected character ')' (U+0029) in name

Why this happened:

  • The table description used angle-bracket style text (>N or <N) in an MDX context.
  • MDX interpreted <N) as JSX-like tag syntax and failed parsing because ) is invalid in a tag name.

3) Faulty and Fixed Content​

Faulty row (conceptually):

| `-size +N/-N` | Match file size (>N or <N) | `find /home/backups -size +500M` | ⭐⭐⭐⭐ |

Applied fix:

| `-size +N/-N` | Match file size (greater than N or less than N) | `find /home/backups -size +500M` | ⭐⭐⭐⭐ |

Updated file:

  • docs/server/linux-server/02-Navigation-and-Filesystem/Search/find.mdx

4) Troubleshooting Steps Performed​

# 1) verify public behavior
curl -I https://brain.id86.net

# 2) inspect tunnel failures
sudo docker logs --tail 200 cloudflared

# 3) inspect Docusaurus errors
sudo docker logs --tail 200 docusaurus

# 4) inspect failing line in container
sudo docker exec docusaurus node -e "const fs=require('fs');const p='/app/docs/server/linux-server/02-Navigation-and-Filesystem/Search/find.mdx';const lines=fs.readFileSync(p,'utf8').split(/\\r?\\n/);for(let i=48;i<=58;i++)console.log(i+': '+lines[i-1]);"

# 5) apply content fix and restart
sudo docker restart docusaurus

# 6) verify origin health
curl -s -o /dev/null -w "%{http_code}" http://172.20.0.8:3000

5) Verification After Fix​

  • Docusaurus build reached success and serve started:
    • [SUCCESS] Generated static files in "build".
    • [SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/
  • Origin check returned 200 on http://172.20.0.8:3000.
  • Public endpoint returned Cloudflare Access redirect (302), not 502.

6) Prevention Checklist​

  1. Avoid raw <...> patterns in MDX prose/table cells unless intentionally using JSX.
  2. Prefer plain wording (greater than, less than) or escaped entities (&lt;, &gt;) in docs text.
  3. Run build validation before restarting production docs container:
sudo docker exec docusaurus sh -lc "cd /app && npm run build"
  1. Keep tunnel log monitoring active for immediate origin failure detection.