Troubleshooting¶
The app takes a long time to open¶
Wait for the live startup banner. Lambda may be cold. CockroachDB may need a new TLS connection. Do not click a teach-back action until the runtime is ready.
If the banner does not clear, open ?mode=replay&scenario=baseline to inspect
the frontend without the backend.
The app shows fixture data in live mode¶
This is a defect. Live mode must show an explicit provider or dependency error. It must not show a replay fixture after an API failure.
Check the API base URL and the signed session request. Then inspect the Lambda logs without printing secret values.
A provider request fails¶
Read the error category. Check the provider key, model name, credit limit, rate limit, timeout, and response schema. The learner's typed response should remain in the form.
Do not change the provider to Gemini, Bedrock, or a local fixture without an explicit configuration change.
Whisper does not load¶
Use typed input. Check browser support, microphone permission, model cache, and available memory. A model download can be large. The byte counter is the source of truth.
Raw audio should never appear in a network request to Orion.
Documentation returns the app shell¶
Use the exact path:
The static site uses .html links. A directory URL such as /docs/ is not the
canonical path for this private S3 origin.
A docs build fails¶
Run:
Fix the first warning. Common causes are a missing nav page, a misspelled relative link, or an unavailable MkDocs plugin.