Troubleshooting

The incident catalogue. Every entry is a real failure that happened, with the symptom you'd see, the root cause, and where the permanent fix lives. Check here before re-deriving a diagnosis — most of these look like something else at first.

Build & deploy

Symptom	Root cause	Fix / where documented
App builds fine but login is blank / Firebase unreachable	VITE_* vars missing in the reusable workflow's build env — secrets don't flow across repos implicitly	pass-through in caller + declared inputs; three-places rule (Build & Deploy)
White screen after a deploy until hard refresh	stale index.html referencing purged chunk hashes	public/_headers: no-cache HTML, long-cache hashed assets
Deploys nondeterministic / env sometimes missing	dual-pipeline race: CF native Git integration + Actions both deploying	exactly one deploy path (Actions); native integration off
Build fails on content	lint gate: bad slug, oversized cases, banned include	fix the content, never the gate (Guidelines)
sql-wasm.wasm 404 / wrong file at runtime	WASM outside the module graph; browser-condition filename mismatch	copy-sql-wasm.mjs; full three-failure story in SQL Pipeline

Judge0 / code running

Symptom	Root cause	Fix
Functions → Judge0 hangs/refuses	Pages egress blocks raw-IP fetches	DNS A record hostname (Code Execution)
C++ compile timeouts in production	<bits/stdc++.h> on a slow VM	banned by lint; incident is the reason
Spurious TLEs in batches; noisy timings	parallel dispatch contending on a single-core VM	concurrency = 1, measured
Python/Java TLE where C++ passes	missing per-language multipliers/overheads	judging layer applies them; clamps too
Wrong MLE verdicts	status mapping trusted Judge0's encoding blindly	cross-check status + signals
Unicode/newline-sensitive wrong answers	raw I/O comparison	base64 round-trip + unified normalizer

AI grading

Symptom	Root cause	Fix
Grading down despite "working" config	cascading free-tier failures: deprecated Gemini model id, Groq rate storms, invalid model string	nine-provider chain; GET health checks per route (AI Pipeline)
Verdicts prefixed [echo provider]	no provider key configured	expected honest degradation — add a key
JSON parse errors from a provider	models decorating JSON with prose/fences	coerceJson + firstBalanced + JSON-only prompts

Firestore & data

Symptom	Root cause	Fix
Attempt write rejected mid-OA	document contained undefined	strip/default optional fields — codebase-wide rule
Reminder emails silently skipping users	profile email written only at creation; Worker reads the mirror	sync on every sign-in + backfill-emails.mjs (Scheduling)
Double-judging / double-sending fears	overlapping cron invocations	updateTime / create preconditions — claims, not locks (Workers)

UI

Symptom	Root cause	Fix
Highlights vanish/duplicate; macOS black-screen; math-adjacent drift	annotations v1 mutated the DOM; offsets measured through KaTeX	data-anchored rewrite (Notes System)
Popover clipped at pane edges	rendered inside overflow:hidden scroller	createPortal to body
Exam chrome unreadable in light mode	hardcoded dark-token colors	all colors via shared CSS variables
Settings edits reverting	derived state computed from stale props	state lifted/keyed correctly; watch for the pattern in new forms

Notes / Docy

Symptom	Root cause	Fix
Notes pane empty with 500	GITHUB_TOKEN missing/expired	rotate in Pages env; functions fail loudly by design (Docy)
Chapters out of order after adding a file	numeric filename convention broken	renumber; ordering relies on numeric sort

This docs site

Symptom	Root cause	Fix
Ask AI: "assistant isn't reachable" in dev	vitepress dev doesn't run Pages Functions	npm run build + wrangler pages dev docs/.vitepress/dist (Development Setup)
Ask AI answers from stale pages	retrieval index predates your edits	index rebuilds on every dev/build; re-run the build

If you fix something not on this page, add it — the entry is part of the fix (Guidelines).