Reference
Troubleshooting
Quick first checks for common symptoms.
Troubleshooting quick hits
| Symptom | First check |
|---|---|
| Turns refuse with a budget message | Analytics → raise budget or disable ENFORCE |
| Turns refuse with a license message | aios license status; renew or (owner) remove the marker |
Dashboard shows only the onboarding screen; API answers 409 onboarding_required | Onboarding isn’t finished (or the vault was reset) — complete the wall: account → about you → provider + key. By design nothing else works until then |
| Banner on every page: vault key missing; provider calls fail with auth errors | aios secrets status; restore the vault-key backup (System → VAULT → RESTORE, or aios secrets kek-restore) — or reset the vault and re-enter keys. Without a backup the stored values are unrecoverable by design |
| A key change doesn’t seem to apply | Provider keys are read from the vault per request — check the row isn’t DISABLED on the Keys page and TEST it there; aios doctor (exit 2 = vault problem). Exception: gateway bot tokens need that profile’s gateway restarted (the Channels RESTART button) |
| Gateway silent on Telegram | journalctl -u aios-gateway; token stored + enabled in the vault (Channels card or aios secrets list); allowlist TELEGRAM_ALLOWED_USER |
| Wrong/odd cached answers | Analytics → clear cache; raise semantic_threshold in harness.json |
| Project answers ignore documents | ⛁ Projects → Reindex; confirm the project selector/--project is set |
| Subdomain 403/404 | project domain assignment re-run; nginx -t; cert exists for apex |
| Disk filling | cargo clean (dev boxes), journalctl --vacuum-size=100M, prune /var/backups/aios |
Site “unreachable” / ERR_NAME_NOT_RESOLVED right after enabling Tailscale | Not a server issue — see Remote access; add Global Nameservers to your tailnet or use --accept-dns=false |