Troubleshooting
| Symptom | Likely area | First check |
|---|---|---|
| Database types missing or stale | Kysely codegen step | bun --filter @repo/database db:codegen |
| Svelte translation key missing | Paraglide output stale | Re-run the compile command in Conventions → Monorepo |
| Mobile auth works locally but not device | API URL or cookie origin | Check the native app’s API base URL (build config), BETTER_AUTH_URL_API, and CORS origins |
| API rejects browser request with 403 | Origin allowlist | Check CORS_ORIGINS and PUBLIC_API_URL |
| Worker consumes dev jobs unexpectedly | Queue suffix mismatch | Ensure producer and worker share QUEUE_SUFFIX |
| Search results stale | Valkey/Meilisearch sync | Run the matching sync script or inspect worker jobs |
| Native decode failure | Contract drift | Regenerate models and validate fixtures |
| Docs page missing | Generated docs not run | bun --filter @repo/docs build |
For production incidents, use Operations → Incident guides.