Skip to main content

502 Recovery - Invalid sidebar_position in cd.mdx

This incident report documents a new brain.id86.net 502 case where Docusaurus failed to start because of invalid frontmatter in one doc file.

Incident Summary​

  • Symptom: brain.id86.net intermittently returned 502 Bad Gateway.
  • Tunnel behavior: Cloudflare tunnel logs showed origin failures (connect: connection refused and later lookup docusaurus ... no such host during restart windows).
  • Container behavior: docusaurus repeatedly restarted.

Root Cause Confirmed​

Build logs showed a hard validation failure in one doc:

  • File: /app/docs/server/linux-server/02-Navigation-and-Filesystem/Listing/cd.mdx
  • Invalid frontmatter:
sidebar_position:

Docusaurus parsed this as null and aborted build with:

"sidebar_position" must be a number

Because startup runs docusaurus build && docusaurus serve, the app never reached serve, which kept the origin unavailable and caused 502.

Recovery Applied​

Updated file on origin bind mount:

  • /opt/docker-data/apps/docusaurus/site/docs/server/linux-server/02-Navigation-and-Filesystem/Listing/cd.mdx

Change:

sidebar_position: 3

Then restarted container and observed successful compile and serve.

Validation​

  • docusaurus logs showed:
    • Generated static files in "build".
    • Serving "build" directory at: http://0.0.0.0:3000/
  • docker ps showed stable Up state (no restart loop).
  • curl -I https://brain.id86.net returned Cloudflare Access 302 redirect (expected protected route), not 502.
  • No new brain.id86.net tunnel origin errors after service stabilized.

Commands Used​

# check public status
curl -I -m 20 https://brain.id86.net

# container status
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

# inspect origin/tunnel errors
sudo docker logs --tail 120 docusaurus
sudo docker logs --tail 120 cloudflared

# restart and monitor
sudo docker restart docusaurus
sudo docker logs --since 2m -f docusaurus

Prevention Notes​

  1. Add MDX/frontmatter preflight before restart (npm run build in CI or pre-deploy script).
  2. Keep startup flow resilient so existing build can still be served while new build is validating.
  3. Add a checklist rule: reject empty numeric frontmatter fields such as sidebar_position:.