Skip to main content

502 After Restart: Google Ads Docs YAML Frontmatter Fix

This document records the incident where brain.id86.net returned 502 Bad Gateway after restarting the docusaurus container, and the fix that restored service.

Issue Observed​

  • brain.id86.net stayed on 502 for more than 3 minutes after sudo docker restart docusaurus.
  • The docusaurus container was not just "building" - it was failing and restarting.

Diagnosis​

  1. Check container status:
sudo docker ps -a --filter "name=^docusaurus$" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

If the status shows Restarting (...), Docusaurus is in a crash loop (not a normal build window).

  1. Read the build logs and look for YAML parsing errors:
sudo docker logs docusaurus --tail 200

The logs showed a frontmatter parsing failure similar to:

YAMLException: incomplete explicit mapping pair ...
Can't process doc metadata for doc at path=/app/docs/visibility/ads/google-ads/01-seo-to-ppc-foundations/01-ppc-vs-seo.mdx

Root Cause​

The Google Ads education docs included YAML frontmatter with a colon (:) in the title value, without quotes.

Example of the invalid frontmatter:

---
title: PPC vs SEO: Same Searcher, Different Rules
---

In YAML, a colon is a special character. When a frontmatter value contains a colon, wrap the value in double quotes.

Correct frontmatter:

---
title: "PPC vs SEO: Same Searcher, Different Rules"
---

This is the same class of issue described in docs/knowledge/docusaurus/10. Troubleshooting/troubleshooting-yaml-syntax-and-links.mdx.

Recovery Applied​

  1. Quote frontmatter titles containing colons in these files:
  • docs/visibility/ads/google-ads/01-seo-to-ppc-foundations/01-ppc-vs-seo.mdx
  • docs/visibility/ads/google-ads/01-seo-to-ppc-foundations/03-metrics-glossary-for-seo.mdx
  • docs/visibility/ads/google-ads/14-exercises-templates-and-glossary/03-glossary.mdx
  1. Restart Docusaurus:
sudo docker restart docusaurus

Verification​

  1. Confirm the build reached serve mode:
sudo docker logs docusaurus --tail 120

Expected success line:

[SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/
  1. Confirm the public endpoint is no longer 502 (Cloudflare Access usually returns a 302):
sudo curl -I -m 15 https://brain.id86.net

Preventive Actions​

  • Treat this as a content lint rule: if title, sidebar_label, or similar frontmatter fields contain :, wrap them in double quotes.
  • Preflight scan for risky titles before a restart:
sudo rg -n '^title: [^\"]*: ' /opt/docker-data/apps/docusaurus/site/docs -g '*.mdx'
  • If you see a 502 after restart, distinguish:
    • build window (container is Up and compiling) vs
    • crash loop (container is Restarting (...))