Troubleshooting

The game opens, but JEV is unavailable

Local and manual modes do not require a key. For live mode, put AI_GATEWAY_API_KEY in the project .env, restart the local Node server, and check GET /api/status. configured: true means a key is present; it does not guarantee provider quota or current upstream availability.

A request fails or returns 429

The browser keeps flying with localDecision and shows the fallback state. A gateway 429 is not silently converted into a fake JEV success. The local /api/decide limiter also returns 429 and a retry interval when its client window is exhausted. Wait, reduce request pressure, or continue locally.

The aircraft behaves oddly

Keep the browser tab visible: hidden pages pause the sortie. Reset with R after changing mission or mode. The model is intentionally arcade-like; HUD altitude is sea-level altitude, while telemetry altitude is terrain-relative. Near terrain or a stall, recovery control takes priority.

The 3D view is blank

Use a desktop browser with WebGL enabled and check the browser console. The diagnostics pages are independent renderer checks and do not call the JEV API.

Read the UI

JEV LIVE means the selected mode can request JEV; the decision panel separately shows accepted responses, latency, and local-wait or failure text.

Verify the checkout

npm ci
npm test
npm run build

If tests pass but live JEV does not, treat them as separate signals: the simulation and adapter tests are network-free, while live mode depends on the local key, gateway response shape, timeout, rate limits, and provider availability.