Troubleshooting

Overview

Use this page as a first-pass administrator checklist. The repository documentation remains canonical for detailed feature state, release gates, and limitations.

Requirements

• Know the running Vaultwarden-Plus version and image tag.
• Keep logs free of tokens, OTP values, recovery links, private keys, auth codes, encrypted keys, and production secrets.
• Check mail transport before debugging mail-dependent features.
• Check feature gates before debugging gated auth features.

Configuration

Useful settings to verify:

DOMAIN=https://your-vault.example.org
SMTP_FROM=vaultwarden@example.org
SMTP_HOST=smtp.example.org
PASSKEY_LOGIN_ENABLED=false
TRUSTED_DEVICE_PROTOTYPE_ENABLED=false
TRUSTED_DEVICE_AUTH_PROTOTYPE_ENABLED=false
TRUSTED_DEVICE_PREVIEW_EMAIL_NOTIFICATIONS=false

Examples

Common checks:

• Account Recovery: organization policy, member enrollment, authorization, Web Vault 2026.4.1, and working mail.
• SMTP: SMTP_FROM, selected transport, credentials, TLS mode, port, and provider-side policy.
• SES: image support for SES plus AWS credential chain.
• DKIM: key material, DKIM_INFOS, DNS, and startup validation.
• Passkeys: DOMAIN, PASSKEY_LOGIN_ENABLED, validated client surface, and stale resident credentials on authenticators.
• Trusted-device/auth-request preview: prototype flags and mail transport.

Troubleshooting

• Mail-dependent OTP and recovery flows can fail closed by design.
• Invalid DKIM config prevents clean startup.
• Rocket built-in TLS is not recommended for production in the current documented security stance.
• Desktop, Android, and iOS passkey login are not assessed.
• Full official-client trusted-device/auth-request challenge/redemption is not confirmed.
• Web Vault upgrades beyond 2026.4.1 are deferred until an accepted upstream artifact is available and separately validated.

Related Pages

• SMTP Configuration
• DKIM Configuration
• Account Recovery
• Passkey Login
• Authentication Request Preview

Canonical Documentation

• Known Limitations
• Security Baseline
• Documentation Index