Skip to content

Chromium Sandbox Debug Prompts

Five prompts for diagnosing Chromium / Puppeteer failures in the publication pipeline. Root cause documented in ADR-014 (v1.6.1): WSL and Docker /dev/shm exhaustion + zygote zombies at --parallel 4. Fix: puppeteer-config.json with --no-sandbox, --disable-dev-shm- usage, --single-process, --no-zygote; default parallel lowered to 2; retry-sequential fallback.

Context for Claude

As MDC you own the mermaid render pipeline. When a render hangs or crashes, walk the ADR-014 decision tree: shm? zygote? sandbox? Headless mode? Test via mmdc -p publications/scripts/puppeteer-config.json.

Prompt 1: Hang triage

MDC, `make pub-diagrams` has hung for 90 seconds. Walk the v1.6.1
triage:
1. Confirm parallel <= 2
2. Confirm puppeteer-config.json passed to mmdc
3. Check /dev/shm free space
4. Inspect any zombie chrome processes
5. Decide: kill + retry, or engage retry-sequential fallback

Produce the decision path.

Expected outcome: triage playbook.

Prompt 2: /dev/shm inspection

On WSL the default /dev/shm tmpfs is 64MB, which Chromium can exhaust
at parallel=4. Tell me:
- The df -h command to inspect shm
- The expected failure symptom (renderer OOM? tab crash?)
- The `--disable-dev-shm-usage` flag alternative
- Why v1.6.1 chose that alternative over raising tmpfs size

Expected outcome: shm inspection note.

Prompt 3: Zygote zombie cleanup

Zygote zombies are processes left behind when Chromium's single-process
mode is not set. Detect them via `ps aux | grep chrome | grep defunct`
and explain why `--single-process` + `--no-zygote` fixes this in the
v1.6.1 config.

Expected outcome: zombie detection + explanation.

Prompt 4: Retry-sequential fallback

When a parallel render times out at 180s wall-clock, render_mermaid.py
queues the timed-out futures for sequential retry after the pool
drains. Walk through the code path:
- Timeout detection
- Queue-add
- Pool-drain hook
- Sequential retry loop
- Final success / permanent-fail classification

Expected outcome: code path narration.

Prompt 5: CI vs local differences

CI containers typically have larger /dev/shm (1GB) than WSL (64MB) but
smaller CPU budgets. Recommend parallel= values for:
- Local WSL developer loop
- GitHub Actions runner
- Self-hosted Docker CI runner

Justify each with the v1.6.1 empirical data (8-15s wall time,
384-386/386 success rate).

Expected outcome: per-environment config recommendations.

  • ADR-014: docs/decisions/ADR-014_chromium_sandbox_puppeteer_config.md
  • Puppeteer config: publications/scripts/puppeteer-config.json
  • Render script: publications/scripts/render_mermaid.py
  • Related prompts: mermaid-diagram-critique-prompts.md, evolution-chromium-sandbox-operator-prompts.md