Error codes
Every problem the app reports carries a code like AIR-201. Each notice in
the app shows its code and what to do, and the code links straight to its entry on this page. API
error responses carry the same codes.
There are 50 codes. Each has its own address, for example
docs.airacegp.com/errors#AIR-208. Codes are permanent: a
number is never reused for a different problem. Severity is Error when
something stopped working, Warning when the app carried on, and
Info for good news.
This list is generated from the app's own error registry, so it always matches the codes the app can show.
By area #
- Settings AIR-101–106
- AI providers AIR-201–214
- Local Ollama AIR-251–255
- Telemetry AIR-301–310
- Voice AIR-401–408
- Web server AIR-501–506
- App AIR-901
Settings #
- What happened
- web_config.json was corrupt (a torn write, a crash mid-save, or a hand edit).
- What to do
- Defaults were loaded and the broken file was kept beside it as web_config.json.corrupt-<time>. Re-apply your settings, or copy values back from that file.
- What happened
- web_config.json could not be written: it is open in another program, read-only, or the disk is full.
- What to do
- Close any editor holding web_config.json, check the folder is writable and has free space, then change the setting again.
- What happened
- Something sent the app a request whose body was not valid JSON, or was JSON but not an object.
- What to do
- Only relevant if you script the app: send a JSON object with Content-Type application/json.
- What happened
- A request named an unknown language, voice or model, or left out a required field.
- What to do
- Pick the value from the list the app offers. Scripts: check the field against the API docs.
- What happened
- Some files could not be removed during a reset: they are open in another program or the folder is read-only.
- What to do
- Close any program holding files in the app folder, then reset again. The list of files that failed is in the notice.
- What happened
- The .env file could not be written: it is open in another program, read-only, or the disk is full.
- What to do
- Close any editor holding .env, check the folder is writable and has free space, then paste the key again.
AI providers #
- What happened
- The provider answered 401/403: the key is wrong, revoked, or lacks access to that model.
- What to do
- Settings → Secrets: paste a fresh key for that provider (no spaces). Check the provider still offers the model named in your model chain.
- What happened
- The provider answered 429: you used its per-minute or per-day allowance (free tiers are small).
- What to do
- Wait, or add another provider to your model chain (Settings → AI → Model chain) with Use fallbacks on, so the next one answers.
- What happened
- The provider did not answer in time (driver questions allow 8 s, other calls 60 s). Usually its queue is busy.
- What to do
- Nothing to do for a one-off. If it keeps happening, move a faster provider up your model chain.
- What happened
- No connection to the provider: no internet, a firewall, a wrong custom URL, or the provider is down.
- What to do
- Check your internet connection. For a custom endpoint, check its URL in Settings → AI.
- What happened
- The provider answered with a 5xx error: a fault on its side.
- What to do
- Usually temporary. Keep a second provider in your model chain so the engineer keeps talking.
- What happened
- The model answered, but not with the JSON the engineer needs (cut off, or prose instead).
- What to do
- A one-off is harmless: the engineer skips that call. If a model does it often, choose another model in your model chain.
- What happened
- Every entry in the model chain is missing its API key (or the Custom entry has no URL), or the chain is empty.
- What to do
- Settings → Secrets: add a key for a provider in your chain, or Settings → AI → Model chain: add a provider you have a key for.
- What happened
- Each provider the engineer tried failed; the notice names the last error's code.
- What to do
- Look up the code named in the message. Add another provider to your chain, and make sure Use fallbacks is on.
- What happened
- The Custom (OpenAI-compatible) provider is missing its URL, model or key.
- What to do
- Settings → AI: fill in the Custom API endpoint URL and model; Settings → Secrets: add CUSTOM_API_KEY.
- What happened
- A provider's key was cleared in Settings → Secrets.
- What to do
- That provider is skipped until a key is added again. Nothing to do if you meant it.
- What happened
- Smart routing is on, but its small-model provider has no API key.
- What to do
- Add that provider's key in Settings → Secrets, or turn Smart routing off (your question chain answers instead).
- What happened
- The provider answered 404: the model name in your chain is misspelt, retired or not available on your plan.
- What to do
- Settings → AI → Model chain: pick the model from the list the app offers for that provider.
- What happened
- The provider answered 402: the account has no credit left or the model is paid-only.
- What to do
- Top up the provider account, or move a free provider up your model chain.
- What happened
- The provider answered 400, 413 or 422: the request was refused (a model that does not accept it, or the prompt is too long).
- What to do
- Try another model for that provider. If you added custom instructions, shorten them.
Local Ollama #
- What happened
- A model chain entry uses Ollama on this PC, but nothing answers on localhost:11434.
- What to do
- Start Ollama (the app, or
ollama servein a terminal), or remove the local Ollama entry from your model chain.
- What happened
- Ollama is running but does not have the model your chain names.
- What to do
- Press Pull model on the notice, or run
ollama pull <model>.
- What happened
ollama pullfailed: a typo in the model name, no internet, or not enough disk space.- What to do
- Check the model name exists on ollama.com, your connection, and free disk space, then pull again.
- What happened
- The
ollamacommand was not found on this PC. - What to do
- Install Ollama from ollama.com, or use a cloud provider in your model chain instead.
- What happened
- A model pull finished.
- What to do
- Nothing to fix. It is used from the next AI call.
Telemetry #
- What happened
- The process that reads the game's telemetry exits repeatedly; the notice shows its last output.
- What to do
- Make sure the game in Settings → General matches the one you are running. For F1 25, check the UDP port and format in the game's telemetry settings. Restart the app if it persists.
- What happened
- Nothing live has arrived since the app started: the game is closed, in a menu or replay, or set to a different game than the one running.
- What to do
- Start the session in the game. Check that Settings → General names the same game. The engineer stays quiet until live data arrives.
- What happened
- The feed was live and then went silent: the game was closed, paused to a menu, or lost the connection.
- What to do
- Return to the session in the game. The engineer resumes by itself when data flows again.
- What happened
- The UDP port (default 20778) is taken by another program, often a second copy of this app or another telemetry tool.
- What to do
- Close the other program or the second copy of the app. Or change the UDP port in the game and in Settings → General.
- What happened
- The ACC broadcasting connection (rivals, gaps) did not answer: broadcasting.json is missing or has a different password, or ACC is still loading.
- What to do
- Check Documents/Assetto Corsa Competizione/Config/broadcasting.json exists and the connection password matches Settings. Without it the engineer works from your car's data only.
- What happened
- The session recording could not be saved: the disk is full, the folder is read-only or an antivirus blocked it.
- What to do
- Free some disk space and check the recordings folder is writable. The live engineer is not affected.
- What happened
- A recording file is damaged (a crash mid-session) or was made by a much older version.
- What to do
- Pick another session. Damaged files are left in place; they are never deleted by the app.
- What happened
- Packets arrive on the telemetry port but do not decode: the game is set to a different UDP Format than the app, or another program is sending to the same port.
- What to do
- In the game, set UDP Format to the year chosen in Settings → Telemetry → UDP packet format (or change that setting to match the game). Bad packets are skipped; good ones still count.
- What happened
- Le Mans Ultimate publishes its telemetry as a Windows shared-memory mapping (LMU_Data), which does not exist on this operating system.
- What to do
- Run the app on the Windows PC the game runs on, or pick another game in Settings → Telemetry. Le Mans Ultimate is not supported yet: the reader has not been tried on a real PC.
- What happened
- The size of the LMU_Data mapping does not match the layout this app was built for (a game update changed it), or the app has no verified layout yet, so it refuses to read rather than show wrong numbers.
- What to do
- Update the app. Check that the game is running as the same user (and with the same administrator rights) as the app, and whether Settings → Gameplay → Enable Plugins in the game needs to be on. Le Mans Ultimate is not supported yet: the reader has not been tried on a real PC.
Voice #
- What happened
- The selected microphone is unplugged, in exclusive use by another app, or blocked by privacy settings.
- What to do
- Plug it in, close other apps using it, allow microphone access in Windows privacy settings, or pick another input in Settings → Audio.
- What happened
- The text-to-speech voice model could not be loaded, so the engineer is muted.
- What to do
- Settings → Voice: pick an installed voice (or install one). If you set PIPER_MODEL_PATH, check the file exists.
- What happened
- This PC could not render the selected voice quickly enough, so calls were arriving late.
- What to do
- Nothing needed. To go back, pick the voice again in Settings → Voice; close heavy apps first.
- What happened
- PIPER_MODEL_PATH points to a file that is missing or is not a Piper .onnx voice.
- What to do
- Settings → Secrets: correct the path, or clear it to use the bundled voices.
- What happened
- The engineer's voice could not be played: no speakers or headset are available, or the chosen one was unplugged.
- What to do
- Plug in or select an output in Settings → Audio, then press Radio check on the Dev page or in Settings.
- What happened
- The offline speech model for your questions did not load (not downloaded yet, or not enough memory).
- What to do
- Connect to the internet once so it can download, or choose the smaller Tiny size in Settings → Voice. Typed questions still work.
- What happened
- The language pack for your chosen language is not installed and could not be downloaded.
- What to do
- Connect to the internet once so it can download. Until then the engineer speaks English.
- What happened
- The wheel, button box or controller your push-to-talk button is on is unplugged, or push to talk is not supported on this system (it needs Windows).
- What to do
- Plug the device back in (it is picked up again within a second), or bind another button in Settings → Audio → Push to talk. Until then the engineer listens by voice detection.
Web server #
- What happened
- The port in Settings → General is in use by another program or not allowed.
- What to do
- Pick another port (e.g. 6970) in Settings → General. The dashboard keeps running on its previous port meanwhile.
- What happened
- LAN access could not bind to all network interfaces (a firewall or another program holds the port).
- What to do
- LAN access was switched back off. Allow the app through your firewall, or change the port, then turn LAN access on again.
- What happened
- A request came from another website, a hostname instead of an IP address, or another device for a PC-only action.
- What to do
- Open the dashboard at the address the app shows (localhost or its IP). Keys and restart only work on the PC running the app.
- What happened
- The page, file or API endpoint asked for does not exist in this version.
- What to do
- Reload the dashboard. If a bookmark is involved, open the dashboard from its start page.
- What happened
- Fetching a file from the internet (such as a voice sample) failed.
- What to do
- Check your internet connection and try again.
- What happened
- The app hit an unexpected error while handling a request.
- What to do
- Try again. If it repeats, restart the app and report the code with the detail shown.
App #
- What happened
- One of the app's workers (voice, AI, tick, microphone, events) raised an error. It was restarted automatically.
- What to do
- Nothing needed if it happens once. If it repeats, restart the app and report the code with the worker named.