Skip to main content

Troubleshooting GSheet Post-Restart 502 Recovery

This incident report documents the 502 error observed on brain.id86.net after restarting the Docusaurus container during Google Sheet migration rollout.

1. Incident Summary​

  • Trigger: sudo docker restart docusaurus
  • Symptom: public site returned 502 Bad Gateway
  • Context: fresh migration of docs/google/google-sheet content
  • Impact: docs temporarily unavailable until build/serve stabilized

2. Primary Root Cause​

Build failed after restart due to MDX parser errors in migrated docs.

Initial fatal error:

  • File: docs/google/google-sheet/04-comparison/google-sheet-vs-nocodb.mdx
  • Error class: Could not parse expression with acorn
  • Parser source: micromark-extension-mdx-expression

This prevented valid static build generation and caused upstream 502 symptoms.

3. Secondary Observations​

  • Temporary webpack cache JSON parse errors appeared during repeated rebuild attempts.
  • These were transient while cache/build artifacts were regenerating.
  • Deprecated config and blog-author warnings were present but non-blocking.

4. Diagnostics Used​

sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
sudo docker logs --tail 200 docusaurus
sudo docker exec docusaurus sh -lc "ps aux | grep -E 'docusaurus serve|node' | grep -v grep"
sudo docker exec docusaurus sh -lc "wget -qO- http://127.0.0.1:3000 | head -n 5"

5. Recovery Actions Applied​

  1. Identified the failing MDX document from container logs.
  2. Applied MDX-safe escaping pass for unsafe brace patterns outside code fences.
  3. Re-ran build until successful static generation completed.
  4. Verified docusaurus serve process was running and serving on port 3000.
  5. Confirmed container-local homepage returned valid HTML.

6. Verification Evidence​

Successful state indicators:

  • Build output included:
    • [SUCCESS] Generated static files in "build".
  • Serve output included:
    • [SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/
  • Runtime process existed:
    • node /app/node_modules/.bin/docusaurus serve --host 0.0.0.0 --port 3000

External note:

  • Public check returned Cloudflare Access login page (not 502), indicating origin recovered.

7. Fast Recovery Playbook​

Use this sequence when restart causes 502 during docs migration:

# 1) Inspect logs for first blocking MDX error
sudo docker logs --tail 300 docusaurus

# 2) Fix the exact failing file(s)
#    (frontmatter quoting, MDX-safe braces/angle brackets, malformed code blocks)

# 3) Rebuild in container
sudo docker exec docusaurus sh -lc "cd /app && npx docusaurus build --no-minify"

# 4) Confirm serve process and local response
sudo docker exec docusaurus sh -lc "ps aux | grep -E 'docusaurus serve|node' | grep -v grep"
sudo docker exec docusaurus sh -lc "wget -qO- http://127.0.0.1:3000 | head -n 5"

8. Prevention Checklist​

  1. Run container build before restarting service after large MDX migrations.
  2. Validate migrated docs for MDX parser hazards (<, {, } outside code fences).
  3. Keep generated frontmatter strictly YAML-safe (quoted values when needed).
  4. Check image/link integrity before final rollout.
  5. Expect short warm-up window after restart; watch logs until serve is healthy.