Troubleshooting

Backend

Symptom	Cause	Fix
RuntimeLockedError: another process holds the runtime lock	Second backend still flocking runtime/runtime.lock	lsof runtime/runtime.lock / `ps aux
IncompatibleRuntimeStateError	state.json version/epoch/tokens mismatch after code change	Delete runtime/state.json or run reset_runtime.py to reseed.
CorruptRuntimeStateError	Partial write or missing attachment	Delete runtime/ and restart — _verify_attachments will re-seed.
409 store.epoch_mismatch	Client sent stale expectedStateEpoch	Fetch fresh GET /bookings/{id}/hub → retry with new epoch + new Idempotency-Key.
409 charge.version_conflict	expectedVersion ≠ current version	Same as above — refetch.
409 idempotency.payload_mismatch	Same key reused with different body/digest	Generate new uuidgen for new intent.
413 attachment.*	Per-file/total ceiling exceeded	Shrink client-side: single ≤10 MiB, sum ≤25 MiB.
422 validation_failed with {field, rule}	Strict model rejects unknown enum/float money/empty id	Read details.errors[].field to locate; fix payload shape.
CORS 401 on /_dev/*	X-Dev-Token missing / constant-time mismatch	Check KX_DEV_TOKEN and header spelling.
KX_WORKERS != 1 startup raises	JSON store is single-process	Run with 1 or drop the env.
Wall-clock deadline flake	KX_DEMO_NOW not set, server clock vs local drift	Launch backend with KX_DEMO_NOW=2026-08-01T12:00:00Z for deterministic deadlines.

Useful one-liners

uv run python scripts/export_openapi.py --check docs/openapi-v1.json --verbose 2>&1 | diff -u docs/openapi-v1.json -
uv run python scripts/verify_fixture_manifest.py --bundle assets/fixtures
lsof runtime/runtime.lock; echo -- ; cat runtime/.kxinspect-runtime
curl -s http://127.0.0.1:8000/api/v1/health | python -m json.tool

Frontend

Symptom	Cause	Fix
Red diagnostic screen on launch	AppConfigException — bad --dart-define	Read listed issues (key+detail); fix API_BASE_URL when DATA_SOURCE=remote, fix URL normalization (must not end with slash etc.).
DatabaseException: no such table	Drift codegen stale	rm lib/core/database/kx_database.g.dart && dart run build_runner build --delete-conflicting-outputs
Golden diff fails	macOS vs Linux rasterization or new token	Regenerate on pinned image (flutter test --update-goldens) and inspect; never raise tolerance.
Navigator route not found	Unknown KxRoutes name or raw Navigator.push	Use goNamed(KxRoutes.chargeName, pathParameters:{...}); check test/architecture forbidden-API failure.
Photo strip overflows page	Nested horizontal scroll	Only KxPhotoStrip may scroll horizontally — remove enclosing SingleChildScrollView axis horizontal.
Contest submit stays disabled at 10 graphemes	ASCII length vs grapheme miscount	Use Characters(reason).length (emoji 🇬🇧 =1, zalgo =1) — see contest_policy.
Outbox never drains offline→online	ConnectivityCubit still offline	flutter run on Chrome requires navigator.onLine — check browser devtools network throttling.
SSE no updates	Last-Event-ID stale / ring trimmed	Expect sync.required; SnapshotCoordinator will refetch; check dio logs for text/event-stream + 429 from chaos.
package:characters miscount	Using String.length	Replace with Characters.
l10n key not found	Missing ARB entry	Add to both app_en.arb + app_cy.arb, run flutter gen-l10n.

Deep-link smoke

flutter run -d chrome --dart-define=DATA_SOURCE=fixture &
sleep 5
# in Chrome address bar:
#   http://localhost:8080/charges/CHG-001/contest
#   http://localhost:8080/charges/CHG-001/photo/0
# Expect 200 and no redirect loop; -1 index should repair to parent with ?notice=photoIndexRepaired.

Docs site

cd documentation
npm ci
npm run typecheck
npm run build   # throws onBrokenLinks == throw

If onBrokenLinks: throw trips, check relative link .md slug (../backend/... vs /docs/backend/...).

When to open an issue

Open against the right repo: seed/fixture/contract → backend repo; widget/l10n/routing → frontend repo. Include stateEpoch/storeRevision from last meta, DataSource + Ids, and reduced curl/ARB reproduction. Contract drift issues should include export_openapi --check diff and both commit SHAs.