Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 saysWhat 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 failedThe 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 ignoredRemove 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 deniedThe 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 installPostgreSQL'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 migrationsYou 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 mentionsWhat to do
isn't valid and a settingFix that setting. The message names it, for example defaults.durations: min (2h) is more than max (1h)
duplicate mapping keyA key appears twice in the same block
The resource ... is new or The openbao settings changedThese need a recreate and health check: docker compose up -d --force-recreate --wait --wait-timeout 120 bouncer

Requesters get errors

The requester seesLikely cause
Exit code 6, the key isn't acceptedThe requester was disabled, or its key was replaced. Check bouncer-admin requester list
Exit code 6, not_requestableThe requester isn't in the resource's requesters list, or the resource doesn't exist
Exit code 6, duration_not_permittedThe 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_failedBouncer 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 4Nobody 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 sent lines 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 list shows the device's status.
  • The phone can't approve, only deny: the resource has require_hardware_uv: true and 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 ps and the last 100 lines of docker 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.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).