Troubleshooting¶

Who is this page for?

Anyone who hits an error running, deploying, or calling GAME. This is the single home for known symptoms; they are grouped by where they show up - local setup, authentication, and runtime/integration. For the why behind the configuration guards see Configuration Reference, and for the request flow see Architecture.

Local setup & first run¶

Symptom	Likely cause / fix
`command not found: uvicorn`	`uvicorn` is installed inside the Poetry virtualenv, not globally. Run it through Poetry: `poetry run uvicorn app.main:app --reload`. If it is still missing, `poetry install` to sync the environment with `pyproject.toml`.
App won’t boot in `prod`/`stage`	A fail-fast secret check tripped. The error names the missing variable (`SECRET_KEY`, `KEYCLOAK_CLIENT_SECRET`, `DB_NAME`) or rejects a wildcard `BACKEND_CORS_ORIGINS=`. See the Fail-fast guards* table in Configuration Reference.
`404` on a freshly created game	You addressed it with your `externalGameId` instead of the internal `gameId` the create call returned. URLs that target a specific record use the internal UUID. See Domain Model.

Authentication¶

Symptom	Likely cause / fix
`401 Invalid authentication credentials`	No/invalid `X-API-Key` header and no valid OAuth2 bearer token. Check the credential and, for token flows, the realm setup in Authentication.
Token expired	Two options: (1) log out and back in to obtain a fresh token; or (2) raise the token lifetime in Keycloak - select your realm, open Clients, pick your client, then on the Advanced tab change Access Token Lifespan to the desired value.

Runtime & integration¶

Symptom	Likely cause / fix
Dashboard shows “Network Error”	Usually a backend `500` whose body the browser dropped because the error response carried no CORS headers. Check the API logs (`docker logs GAME_API_DEV`) for the real traceback rather than trusting the browser message. The middleware ordering behind this is explained in Architecture.

Still stuck?¶

Open a GitHub issue with your version/commit, the endpoint and method, whether the strategy is a built-in class or a DSL strategy, your deployment mode, and the relevant docker logs output. For a security problem, follow the Security policy instead of filing a public issue.