Find your symptom in the table for your area. Commands assume Docker, run from the repository folder. For a manual setup, replace docker compose exec api with the same command run directly, such as uv run polyweb-users ....
Sign in fails with “The server returned a refresh credential to the browser.”
POLYWEB_AUTH_BROWSER_ORIGINS is empty or does not match the dashboard address
Set it to the exact origin as a JSON list, such as ["http://localhost:3000"], then run docker compose up -d
Sign in or register fails, or the API logs POLYWEB_AUTH_JWT_SECRET is required for account authentication
The signing secret is missing or shorter than 32 bytes
Set POLYWEB_AUTH_JWT_SECRET to 32 or more random bytes in .env (openssl rand -hex 32), then run docker compose up -d
Registration works but you cannot create a project
Registered accounts are ordinary users. Only system admins create projects
Create an admin with the command below, then sign in with it
429 while signing in or registering
Rate limit on attempts (15-minute window)
Wait for the Retry-After time
400 on sign in
Wrong email or password, or a deactivated account
Check the credentials. A system admin can tell you whether the account was deactivated
422 on registration
Password outside 12 to 128 characters, or extra fields in the body
Send only email and password
Port already in use when running docker compose up
Another program uses 3000, 8001, or 8000
Set UI_PORT, API_PORT, or MCP_PORT in .env, update POLYWEB_AUTH_BROWSER_ORIGINS if you changed UI_PORT, then run docker compose up -d
The dashboard returns 502 after you recreate the api container
The dashboard proxy lost the API server
Run docker compose restart ui
A container is unhealthy
The API server is still starting, or crashed
Run docker compose logs api and read the last error
Create the first system admin once the API is up. The password is a masked prompt, so run it in an interactive terminal (piping a password fails, and the first run can take a few seconds):
Polyweb cannot open the database ... reset required
The file is from an older alpha, is unversioned, or is from a newer Polyweb version
For a newer version, use a compatible Polyweb. For an old file, stop Polyweb, move the database and its -wal and -shm files, or point POLYWEB_DB at a new path. Accounts, provider keys, and settings must then be entered again
polyweb-users fails because the database is missing
The API has not created the database yet
Wait for the API to start. In a manual setup, run uv run polyweb-db upgrade first
Provider keys no longer work after a restore
The database was restored without its matching master key
Restore .secret_key from the same backup, or enter the provider keys again
Everything is gone after docker compose down -v
-v deletes the polyweb-data volume, including the database and master key
Use docker compose down to keep data. Restore from a backup (see Back up and upgrade)
The project has no enabled binding with a key for that operation
In the dashboard, add a provider key, put it in a key pool, bind the pool to the project, and turn the operation on. See Provider keys and pools and Project providers
A new binding returns nothing
A new binding starts with no operations enabled
Enable search or fetch on the binding
fetch fails on Brave
Brave supports search only
Route fetch to another provider
429 from a provider
Rate limit
Wait for Retry-After, then retry with backoff
402 from a provider
Budget spent or no access
Top up, wait for the reset, or switch provider. Do not retry immediately
