Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
404 model_not_found for a seeded model | Seed ran before the first portal sign-in; OpenAI bootstrap skipped | Add the credential and deployments on Models, or wipe the DB volume and redo setup in order (portal boot, then seed) |
502 upstream_unavailable on every model | Invalid OPENAI_API_KEY, or credential encrypted with the wrong ZEALLM_ENCRYPTION_KEY | Verify the key. Do not rotate the encryption key after credentials are stored without re-encryption |
| 401 from OpenAI (passed through) | Stale openai-default credential from an old OPENAI_API_KEY at first boot | Delete the credential on Models, add a new one, re-add deployments |
docker compose up fails: port 3000 / 8080 in use | Another process is already using the portal or gateway port | Stop that process, or run against the servers already listening |
| Invite warning banner | No SMTP | Expected locally — the account still works |
| Key block / revoke not picked up | Redis down; gateway on TTL fallback | Restart Redis, or wait ZEAGATE_CACHE_TTL_SECONDS (default 15s) |
| Budget demo does not trip | Spend is recorded asynchronously | Make another call after a short lag |
Sign-in rejected not_invited | Email has no User row and is not in ZEALLM_ADMIN_EMAILS | Invite from Users, or sign in as a bootstrap admin |
JWTSessionError on /login | Stale session cookie signed with an old AUTH_SECRET | Open /logout, or clear site cookies. Keep root .env and portal/.env AUTH_SECRET in sync |
| AccessDenied on sign-in | Postgres is down (Docker Desktop stopped) | Start Docker Desktop, then docker compose up -d db redis |
Reset a local stack
docker compose down -v
docker compose up -d --build
Then sign in as a bootstrap admin so the portal can bootstrap provider credentials before you run any seed script.
After a reboot
The portal still needs the database and Redis containers. Start Docker Desktop first.