Vaultwarden Troubleshooting
Work from the outside in: server reachable → versions compatible → credentials → feature flags. Most "wrong password" reports on Vaultwarden are version or proxy problems, not passwords.
Quick diagnostics
VW_URL="https://vault.example.com"
curl -sS -o /dev/null -w 'alive %{http_code}\n' "$VW_URL/alive"
curl -fsS "$VW_URL/api/version"; echo
curl -fsS "$VW_URL/api/config" | jq '{emulates: .version, gitHash, server: .server.name}'
bw --version
bw status | jq '{serverUrl, status, lastSync, userEmail}'
Then run /vaultwarden-dev:check-version for a verdict on the CLI/server pair. On the server side: docker logs --tail 200 <container>; raise detail temporarily with LOG_LEVEL=debug (restart-only, and debug logs contain request details — turn it back off).
Version coupling
Most "right password, still rejected" reports are a client/server version mismatch: bw 2026.9.x needs Vaultwarden 1.37.4+ (older servers answer 404 on key-management/user-key-id), 2026.8 clients need 1.37.2+, 2026.7 clients 1.37.0+, and Vaultwarden 1.37.4+ rejects outdated CLIs that still call the removed /api/accounts/prelogin. Full table and what to pin per server version: references/version-matrix.md. Upgrade the server first, then the clients, and read the release notes at https://github.com/dani-garcia/vaultwarden/releases before each upgrade.
Login and token errors
| Error |
Cause |
Fix |
Username or password is incorrect. Try again |
wrong password, wrong bw config server, KDF mismatch in a hand-rolled hash, or a version mismatch (above) |
check bw config server, versions; use the API-key login |
TwoFactorProviders2 in a 400 body |
2FA required on the password grant |
use the personal API key (bw login --apikey), which skips 2FA |
Invalid client_id / Malformed client_id |
missing user. or organization. prefix |
copy the full client_id from the web vault |
Incorrect client_secret |
key rotated |
fetch the current key in the web vault |
Scope not supported |
wrong scope |
api (user key), api.organization (org key), api offline_access (password) |
This user has been disabled |
admin disabled the account |
POST /admin/users/<id>/enable |
Please verify your email before trying again. |
SIGNUPS_VERIFY=true |
verify via the mail, or check SMTP |
Could not send login notification email |
new device + REQUIRE_DEVICE_EMAIL=true + SMTP failing |
fix SMTP or reuse a known device_identifier |
SSO sign-in is required |
SSO_ONLY=true |
log in with bw login --sso, or use the API key |
{"error":"invalid_grant"} |
refresh token expired or revoked (password change, deauth) |
log in again |
"Vault is locked" from bw |
BW_SESSION missing or stale |
export BW_SESSION="$(bw unlock --passwordenv BW_PASSWORD --raw)" |
Rate limits (429)
| Message |
Limiter |
Default |
Too many login requests |
LOGIN_RATELIMIT_SECONDS / LOGIN_RATELIMIT_MAX_BURST |
60 s / 10, per IP; password and 2FA steps share the budget |
Too many admin requests / Too many requests, try again later. on /admin |
ADMIN_RATELIMIT_SECONDS / ADMIN_RATELIMIT_MAX_BURST |
300 s / 3 |
Too many requests on prelogin / Send access |
UNAUTHENTICATED_RATELIMIT_* |
60 s / 50 |
If every user trips limits at once, the reverse proxy is not forwarding the client IP: set IP_HEADER to the header the proxy sends (X-Real-IP or X-Forwarded-For) and, for X-Forwarded-For, IP_HEADER_TRUSTED_PROXIES (1.37.4+).
Admin panel
| Symptom |
Cause |
Fix |
| "The admin panel is disabled" |
ADMIN_TOKEN unset |
set it (Argon2 hash via vaultwarden hash) and restart |
Invalid admin token, please try again. with the right value |
$ in the PHC hash eaten by docker-compose interpolation |
escape as $$ or use ADMIN_TOKEN_FILE |
| token change has no effect |
config.json overrides the environment |
change it in the admin page, or remove the key from config.json |
401 Unauthorized / Session expired on JSON routes |
missing or expired VW_ADMIN cookie |
log in again; see vaultwarden-dev:admin-panel |
| not-found error on a POST route |
missing Content-Type: application/json |
add the header, even for empty bodies |
| all admin sessions dropped after restore |
rsa_key.pem changed |
restore it with the database |
Organizations and members
| Symptom |
Cause |
Fix |
| member stuck in "Accepted" |
needs confirmation with the org key |
bw confirm org-member <member-id> --organizationid <org-uuid> |
| invite email never arrives |
SMTP not configured / failing |
POST /admin/test/smtp; without SMTP the invite is recorded and the user can register directly |
Resource not found / Organization not found on /api/organizations/... |
wrong org id or the token's user is not Admin/Owner there |
check GET /api/accounts/profile → organizations[].type |
| groups missing, import skips groups |
ORG_GROUPS_ENABLED=false |
enable (restart-only) |
| events endpoint empty |
ORG_EVENTS_ENABLED=false |
enable (restart-only); history starts then |
Bitwarden Public API calls 404 (/api/public/members, …) |
Vaultwarden implements only /api/public/organization/import |
use the client API routes instead |
bws / Secrets Manager does not work |
not implemented in Vaultwarden |
use items with custom fields via bw |
Clients and sync
| Symptom |
Cause |
Fix |
| changes do not appear live on other devices |
WebSocket not proxied |
proxy /notifications/hub with Upgrade headers; ENABLE_WEBSOCKET=true |
| mobile apps do not update in the background |
push not configured |
PUSH_ENABLED=true with an installation id/key from bitwarden.com/host |
| attachments or icons broken, wrong links in mails |
DOMAIN wrong (scheme, host or path) |
set the exact external URL |
bw TLS errors with a private CA |
Node does not trust it |
export NODE_EXTRA_CA_CERTS=<ca.pem>; keep TLS verification on — with it off, anyone on the path can capture the master-password hash and session |
bw sync hangs |
large vault or a stuck proxy connection |
retry with BITWARDENCLI_DEBUG=true (prints tokens — keep the output private) |
bw still talks to the old server |
config is per data dir |
bw logout, bw config server <url>, log in again; use BITWARDENCLI_APPDATA_DIR per server |
Server state after an upgrade or restore
- "0 users" after an upgrade: the container started with an empty or wrong data volume (the folder
DATA_FOLDER points at) — check the mount before anything else; do not create new accounts.
- After restoring
db.sqlite3, delete a stale db.sqlite3-wal from the old run before starting, or the restore is partly undone.
- 503 errors: the DB pool is exhausted or the database is unreachable; check
DATABASE_URL and DATABASE_MAX_CONNS.
When to escalate
Check open issues and discussions at https://github.com/dani-garcia/vaultwarden — most client-compatibility breaks are reported there within days of a client release. Report Vaultwarden problems there, not to Bitwarden support — Bitwarden does not support third-party servers and will ask you to reproduce on its own.
1---2name: troubleshoot-283description: This skill should be used when the user reports Vaultwarden errors — "Username or password is incorrect" with the right password, "404 on user-key-id", "Vaultwarden 401 or 429", "invites not arriving", "bw sync hangs" — or needs to diagnose a self-hosted Vaultwarden or bw failure.4metadata:5 source: https://skillmd.com/skills/agents-store/troubleshoot-286---78# Vaultwarden Troubleshooting910Work from the outside in: server reachable → versions compatible → credentials → feature flags. Most "wrong password" reports on Vaultwarden are version or proxy problems, not passwords.1112## Quick diagnostics1314```bash15VW_URL="https://vault.example.com"16curl -sS -o /dev/null -w 'alive %{http_code}\n' "$VW_URL/alive"17curl -fsS "$VW_URL/api/version"; echo18curl -fsS "$VW_URL/api/config" | jq '{emulates: .version, gitHash, server: .server.name}'19bw --version20bw status | jq '{serverUrl, status, lastSync, userEmail}'21```2223Then run `/vaultwarden-dev:check-version` for a verdict on the CLI/server pair. On the server side: `docker logs --tail 200 <container>`; raise detail temporarily with `LOG_LEVEL=debug` (restart-only, and debug logs contain request details — turn it back off).2425## Version coupling2627Most "right password, still rejected" reports are a client/server version mismatch: `bw` 2026.9.x needs Vaultwarden 1.37.4+ (older servers answer 404 on `key-management/user-key-id`), 2026.8 clients need 1.37.2+, 2026.7 clients 1.37.0+, and Vaultwarden 1.37.4+ rejects outdated CLIs that still call the removed `/api/accounts/prelogin`. Full table and what to pin per server version: [references/version-matrix.md](references/version-matrix.md). Upgrade the server first, then the clients, and read the release notes at https://github.com/dani-garcia/vaultwarden/releases before each upgrade.2829## Login and token errors3031| Error | Cause | Fix |32|---|---|---|33| `Username or password is incorrect. Try again` | wrong password, wrong `bw config server`, KDF mismatch in a hand-rolled hash, or a version mismatch (above) | check `bw config server`, versions; use the API-key login |34| `TwoFactorProviders2` in a 400 body | 2FA required on the password grant | use the personal API key (`bw login --apikey`), which skips 2FA |35| `Invalid client_id` / `Malformed client_id` | missing `user.` or `organization.` prefix | copy the full `client_id` from the web vault |36| `Incorrect client_secret` | key rotated | fetch the current key in the web vault |37| `Scope not supported` | wrong `scope` | `api` (user key), `api.organization` (org key), `api offline_access` (password) |38| `This user has been disabled` | admin disabled the account | `POST /admin/users/<id>/enable` |39| `Please verify your email before trying again.` | `SIGNUPS_VERIFY=true` | verify via the mail, or check SMTP |40| `Could not send login notification email` | new device + `REQUIRE_DEVICE_EMAIL=true` + SMTP failing | fix SMTP or reuse a known `device_identifier` |41| `SSO sign-in is required` | `SSO_ONLY=true` | log in with `bw login --sso`, or use the API key |42| `{"error":"invalid_grant"}` | refresh token expired or revoked (password change, deauth) | log in again |43| "Vault is locked" from `bw` | `BW_SESSION` missing or stale | `export BW_SESSION="$(bw unlock --passwordenv BW_PASSWORD --raw)"` |4445## Rate limits (429)4647| Message | Limiter | Default |48|---|---|---|49| `Too many login requests` | `LOGIN_RATELIMIT_SECONDS` / `LOGIN_RATELIMIT_MAX_BURST` | 60 s / 10, per IP; password and 2FA steps share the budget |50| `Too many admin requests` / `Too many requests, try again later.` on `/admin` | `ADMIN_RATELIMIT_SECONDS` / `ADMIN_RATELIMIT_MAX_BURST` | 300 s / 3 |51| `Too many requests` on prelogin / Send access | `UNAUTHENTICATED_RATELIMIT_*` | 60 s / 50 |5253If **every** user trips limits at once, the reverse proxy is not forwarding the client IP: set `IP_HEADER` to the header the proxy sends (`X-Real-IP` or `X-Forwarded-For`) and, for `X-Forwarded-For`, `IP_HEADER_TRUSTED_PROXIES` (1.37.4+).5455## Admin panel5657| Symptom | Cause | Fix |58|---|---|---|59| "The admin panel is disabled" | `ADMIN_TOKEN` unset | set it (Argon2 hash via `vaultwarden hash`) and restart |60| `Invalid admin token, please try again.` with the right value | `$` in the PHC hash eaten by docker-compose interpolation | escape as `$$` or use `ADMIN_TOKEN_FILE` |61| token change has no effect | `config.json` overrides the environment | change it in the admin page, or remove the key from `config.json` |62| 401 `Unauthorized` / `Session expired` on JSON routes | missing or expired `VW_ADMIN` cookie | log in again; see `vaultwarden-dev:admin-panel` |63| not-found error on a POST route | missing `Content-Type: application/json` | add the header, even for empty bodies |64| all admin sessions dropped after restore | `rsa_key.pem` changed | restore it with the database |6566## Organizations and members6768| Symptom | Cause | Fix |69|---|---|---|70| member stuck in "Accepted" | needs confirmation with the org key | `bw confirm org-member <member-id> --organizationid <org-uuid>` |71| invite email never arrives | SMTP not configured / failing | `POST /admin/test/smtp`; without SMTP the invite is recorded and the user can register directly |72| `Resource not found` / `Organization not found` on `/api/organizations/...` | wrong org id or the token's user is not Admin/Owner there | check `GET /api/accounts/profile` → `organizations[].type` |73| groups missing, import skips groups | `ORG_GROUPS_ENABLED=false` | enable (restart-only) |74| events endpoint empty | `ORG_EVENTS_ENABLED=false` | enable (restart-only); history starts then |75| Bitwarden Public API calls 404 (`/api/public/members`, …) | Vaultwarden implements only `/api/public/organization/import` | use the client API routes instead |76| `bws` / Secrets Manager does not work | not implemented in Vaultwarden | use items with custom fields via `bw` |7778## Clients and sync7980| Symptom | Cause | Fix |81|---|---|---|82| changes do not appear live on other devices | WebSocket not proxied | proxy `/notifications/hub` with `Upgrade` headers; `ENABLE_WEBSOCKET=true` |83| mobile apps do not update in the background | push not configured | `PUSH_ENABLED=true` with an installation id/key from bitwarden.com/host |84| attachments or icons broken, wrong links in mails | `DOMAIN` wrong (scheme, host or path) | set the exact external URL |85| `bw` TLS errors with a private CA | Node does not trust it | `export NODE_EXTRA_CA_CERTS=<ca.pem>`; keep TLS verification on — with it off, anyone on the path can capture the master-password hash and session |86| `bw sync` hangs | large vault or a stuck proxy connection | retry with `BITWARDENCLI_DEBUG=true` (prints tokens — keep the output private) |87| `bw` still talks to the old server | config is per data dir | `bw logout`, `bw config server <url>`, log in again; use `BITWARDENCLI_APPDATA_DIR` per server |8889## Server state after an upgrade or restore9091- "0 users" after an upgrade: the container started with an empty or wrong data volume (the folder `DATA_FOLDER` points at) — check the mount before anything else; do not create new accounts.92- After restoring `db.sqlite3`, delete a stale `db.sqlite3-wal` from the old run before starting, or the restore is partly undone.93- 503 errors: the DB pool is exhausted or the database is unreachable; check `DATABASE_URL` and `DATABASE_MAX_CONNS`.9495## When to escalate9697Check open issues and discussions at https://github.com/dani-garcia/vaultwarden — most client-compatibility breaks are reported there within days of a client release. Report Vaultwarden problems there, not to Bitwarden support — Bitwarden does not support third-party servers and will ask you to reproduce on its own.