Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
On this page
Troubleshooting the server
Check the logs first: docker compose logs bouncer, and docker compose logs postgres if PostgreSQL is involved. The server's messages say what to fix, and never contain keys, tokens or secret values.
The server doesn't start
The server stops at start-up if its settings are wrong, and Docker restarts it after a pause, so the same message repeats in the log. From 0.5.6, a sealed or unreachable OpenBao, or a refused AppRole login, leaves it running with 503 and the credential backend isn't ready. Earlier servers, such as 0.3.8, can exit and restart instead (When Bouncer is unavailable).
| The log says | What to do |
|---|---|
can't read the AppRole role_id file /run/secrets/bouncer-role-id: ... (before 0.5.6: start-up stops; from 0.5.6: keeps running with 503 backend_auth_failed) | The file is missing, or not readable by user 10001. Redo install step 3 |
bouncer-entrypoint: can't read the database password file ... | The same, for bouncer-db-password |
the config file /etc/bouncer/bouncer.yaml was refused: ... | The reason follows. That's the path inside the container; on the server, edit /etc/bouncer/config/bouncer.yaml. Then docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer |
can't connect to the database: ... password authentication failed | The password file changed after the database was made. Put the old one back, or change the password properly |
can't update auth/token/create/...; run the role kit's setup.sh (0.5.6 and earlier) | The resource is missing from the role kit's resources file, or setup.sh has not run since it was added. These versions stop the whole server. From 0.5.7, only that resource answers 503 resource_not_provisioned (When Bouncer is unavailable) |
the credential backend isn't ready with an error logging in to OpenBao with AppRole (server 0.5.6 keeps running, answering 503 backend_auth_failed) | The secret_id may have expired or been destroyed, or SECRET_ID_BOUND_CIDRS doesn't include the server. Follow Replace the OpenBao secret_id, including recreating the Compose container so the new file is mounted and a fresh login is checked |
the credential backend isn't ready with OpenBao is sealed (answering 503 backend_sealed) | OpenBao is sealed. Unseal it; the server recovers by itself |
BOUNCER_WAIT_FOR_OPENBAO is ignored | Remove the setting from deploy/compose/.env. From 0.5.6 the server doesn't need to wait for OpenBao |
postgres exits with code 2: ls: cannot open directory '/docker-entrypoint-initdb.d/': Permission denied | The checkout isn't readable by PostgreSQL's user, usually because of a strict umask. chmod -R a+rX ~/bouncer/deploy/compose, then docker compose up -d. We hit this in testing |
role "bouncer" does not exist, or the password is refused on a brand-new install | PostgreSQL's first start stopped part way. On a new install only, start over with docker compose down -v and docker compose up -d. Never do this once Bouncer is in use: -v deletes the database |
| A migration error, or the server refuses the database's migrations | You started an older version on a database a newer version migrated. See Roll back |
Config reload is refused
bouncer-admin config reload exits with code 6 and the reason. The old config stays loaded.
| The message mentions | What to do |
|---|---|
isn't valid and a setting | Fix that setting. The message names it, for example defaults.durations: min (2h) is more than max (1h) |
duplicate mapping key | A key appears twice in the same block |
The resource ... is new or The openbao settings changed | These need a recreate and health check: docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer |
Requesters get errors
| The requester sees | Likely cause |
|---|---|
| Exit code 6, the key isn't accepted | The requester was disabled, or its key was replaced. Check bouncer-admin requester list |
Exit code 6, not_requestable | The requester isn't in the resource's requesters list, or the resource doesn't exist |
Exit code 6, duration_not_permitted | The duration is outside the resource's range, or a disabled preset |
| Exit code 12, 13 or 14, "The Bouncer server is running, but its vault …" | OpenBao is sealed (12), unreachable (13), or refusing the server's login (14). An outage, not a refusal: see When Bouncer is unavailable |
| Exit code 15, "the proxy in front of it got no answer" | Your HTTPS front end (for example tailscale serve) is up, but bouncer-server isn't answering. Check docker compose ps and the server's log |
issuance_failed | Bouncer could not get a credential from OpenBao for a reason other than an outage or a missing kit role. Check the server log for OpenBao's reason. |
| Exit code 6 reading from OpenBao, "permission denied" | The role kit's paths don't match the resource's kv entries |
| Requests time out with exit code 4 | Nobody approved in time. Check approvers have paired devices, and that push works, or that they open the app |
Exit codes and errors lists every code.
Approvers don't see requests
- No notification, but the request is in the app: push is off or failing. Check
push sentlines in the log (Push notifications). Windows never gets pushes; the app must be running. - Not in the app at all: the person isn't in the resource's
approvers, or their device was revoked.bouncer-admin device listshows the device's status. - The phone can't approve, only deny: the resource has
require_hardware_uv: trueand the phone's key doesn't verify the user on every signature, or the pairing settings no longer accept the key type (Device keys).
Revokes say "not confirmed"
bouncer revoke or the kill switch exits 10 when OpenBao didn't confirm every token's revoke. The cutoff has still happened: no new token can be issued. The server retries the revokes every few seconds, then every minute, until they succeed or the tokens expire. Check that OpenBao is unsealed and reachable from the server.
Collecting information for a bug report
curl -s http://127.0.0.1:8080/v1/health(the version);docker compose psand the last 100 lines ofdocker compose logs bouncer;- the exact command and its output.
Remove your hostnames and any IDs you don't want to share before you send them. None of these contain secrets.