# 1. Verificar que el contenedor está corriendo
docker compose ps

# 2. Ver logs recientes
docker compose logs --tail=100 vaultwarden

# 3. Verificar salud del contenedor
docker inspect vaultwarden | grep -A 10 State

# 4. Comprobar recursos
docker stats vaultwarden --no-stream

# 5. Verificar red
docker network inspect proxy

🚫 Contenedor No Inicia

Síntoma

docker compose up -d falla o el contenedor se detiene inmediatamente.

Diagnóstico

# Ver error exacto
docker compose logs vaultwarden

# Ver eventos de Docker
docker events --filter container=vaultwarden

Causas Comunes

1. Variable de Entorno Faltante

Error: Missing ADMIN_TOKEN o similar

Solución:

# Verificar variables
docker compose config

# Añadir variable faltante en .env o Portainer
ADMIN_TOKEN=tu_token_aqui

2. Puerto Ya en Uso

Error: address already in use o bind: address already in use

Solución:

# Identificar qué usa el puerto (ej: 8080)
netstat -tuln | grep 8080

# Si necesitas cambiar puertos, usa Traefik o NPM
# Vaultwarden no expone puertos directamente

3. Volumen Corrupto

Error: database disk image is malformed

Solución:

# Verificar integridad
docker run --rm -v vaultwarden_data:/data \
  nouchka/sqlite3 sqlite3 /data/db.sqlite3 "PRAGMA integrity_check;"

# Si falla, restaurar desde backup (ver Backup y Restauración)

4. Permisos Incorrectos

Error: Permission denied en logs

Solución:

# Dar permisos correctos al volumen
docker run --rm -v vaultwarden_data:/data alpine chown -R 1000:1000 /data

🌐 No Puedo Acceder a la Web

Síntoma

https://vaultwarden.tudominio.com no responde o da timeout.

Diagnóstico Paso a Paso

1. Verificar Contenedor

# ¿Está corriendo?
docker compose ps

# Si está "unhealthy" o "exited"
docker compose logs vaultwarden

2. Verificar Red

# ¿Está en la red proxy?
docker network inspect proxy | grep vaultwarden

# Si no está, recrear
docker compose down && docker compose up -d

3. Verificar Proxy

Con Traefik:

# Ver logs de Traefik
docker logs traefik | grep vaultwarden

# Verificar routers en el dashboard (http://traefik:8080)

Con NPM:

Accede a NPM (http://npm:81)
Proxy Hosts → Verifica que existe entrada para Vaultwarden
Status debe ser "Online"

4. Verificar DNS

# ¿El dominio resuelve a tu IP?
nslookup vaultwarden.tudominio.com

# Prueba desde otra máquina
ping vaultwarden.tudominio.com

5. Verificar Firewall

# ¿Puertos 80/443 abiertos?
sudo ufw status | grep -E '80|443'

# Si están bloqueados
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Soluciones Específicas

Error 502 Bad Gateway

Causa: El proxy no puede conectar con Vaultwarden

Solución:

# 1. Verificar que ambos están en la misma red
docker network inspect proxy

# 2. Verificar nombre del contenedor
docker compose ps  # Debe ser exactamente "vaultwarden"

# 3. Probar conectividad interna
docker exec -it traefik ping vaultwarden  # O desde NPM

Error 503 Service Unavailable

Causa: Contenedor caído o reiniciando constantemente

Solución:

# Ver por qué se reinicia
docker compose logs vaultwarden

# Recrear contenedor
docker compose down && docker compose up -d

Error 404 Not Found (con Traefik)

Causa: Router no configurado o regla incorrecta

Solución:

# Verificar labels
docker inspect vaultwarden | grep -A 20 Labels

# Debe incluir: traefik.http.routers.vaultwarden.rule=Host(`...`)

# Si falta, verificar override de Traefik
cat docker-compose.override.yml

No Puedo Iniciar Sesión

Causa 1: Contraseña Maestra Incorrecta

Síntoma: "Invalid username or password"

Solución:

⚠️ La contraseña maestra NO se puede recuperar
Si la olvidaste, no hay solución sin backup
Crear cuenta nueva como último recurso

Causa 2: Email No Verificado

Síntoma: "Email not verified"

Solución:

# Opción 1: Reenviar email de verificación (requiere SMTP)
# Desde /admin → Users → Resend invitation

# Opción 2: Verificar manualmente en la DB (avanzado)
docker exec -it vaultwarden sqlite3 /data/db.sqlite3 \
  "UPDATE users SET email_verified = 1 WHERE email = 'usuario@email.com';"

Causa 3: 2FA Perdido

Síntoma: No tienes acceso al código 2FA

Solución:

# Desactivar 2FA para un usuario (desde DB)
docker exec -it vaultwarden sqlite3 /data/db.sqlite3 \
  "DELETE FROM twofactor WHERE user_uuid = (SELECT uuid FROM users WHERE email = 'usuario@email.com');"

Session Expirada Constantemente

Causa: Cookies bloqueadas o DOMAIN incorrecto

Solución:

# Verificar variable DOMAIN
docker compose exec vaultwarden env | grep DOMAIN

# Debe coincidir EXACTAMENTE con la URL de acceso
# Correcto: DOMAIN=https://vaultwarden.tudominio.com
# Incorrecto: DOMAIN=https://vaultwarden.tudominio.com/ (barra final)

🔌 WebSocket No Funciona

Síntoma

Sincronización muy lenta (minutos en lugar de segundos).

Diagnóstico

# 1. Verificar que WebSocket está habilitado
docker compose exec vaultwarden env | grep WEBSOCKET

# 2. Ver puerto en logs
docker compose logs vaultwarden | grep -i websocket

# Debería mostrar: "WebSocket server listening on 0.0.0.0:3012"

Soluciones por Configuración

Con Traefik

# Verificar router de WebSocket
docker inspect vaultwarden | grep -i "vaultwarden-ws"

# Debe existir router para /notifications/hub en puerto 3012

Si falta:

Verifica que usas docker-compose.override.traefik.yml.example
Recrear: docker compose down && docker compose up -d

Con NPM

Problema más común: WebSocket Support no activado

Probar WebSocket

# Instalar wscat (si no lo tienes)
npm install -g wscat

# Probar conexión
wscat -c wss://vaultwarden.tudominio.com/notifications/hub

# Si funciona, verás: "Connected"
# Si falla, problema de configuración del proxy

📧 Problemas con Email (SMTP)

Emails No Se Envían

Diagnóstico

# Ver errores SMTP en logs
docker compose logs vaultwarden | grep -i smtp

# Errores comunes:
# - "Connection refused": Host/puerto incorrectos
# - "Authentication failed": Usuario/password incorrectos
# - "TLS error": SMTP_SECURITY incorrecto

Causas Comunes

1. Host o Puerto Incorrectos

Solución:

# Gmail
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587

# Outlook
SMTP_HOST=smtp.office365.com
SMTP_PORT=587

# Otros: verificar documentación del proveedor

2. SMTP_SECURITY Incorrecto

Solución:

# Para puerto 587 (común)
SMTP_SECURITY=starttls

# Para puerto 465
SMTP_SECURITY=ssl

# Para puerto 25 (raro, inseguro)
SMTP_SECURITY=off

3. Credenciales Incorrectas

Gmail requiere App Password:

https://myaccount.google.com/security
2-Step Verification → ON
App passwords → Generate
Usa el password generado (no tu password normal)

4. Firewall Bloqueando Puerto SMTP

Solución:

# Probar conectividad SMTP desde el contenedor
docker compose exec vaultwarden sh
apk add --no-cache openssl
openssl s_client -starttls smtp -connect smtp.gmail.com:587
# Debería conectar

Probar SMTP desde el Panel de Administración

Ve a /admin
Scroll down a SMTP Settings
Introduce un email de prueba
Send test email
Revisa los logs si falla

🔒 Problemas con Certificados SSL

Certificado Inválido o Autofirmado

Con Traefik

Diagnóstico:

# Ver certificados gestionados por Traefik
docker exec traefik ls -la /acme.json

# Ver logs de Let's Encrypt
docker logs traefik | grep -i acme

Causas comunes:

DNS no apunta al servidor: Verifica nslookup vaultwarden.tudominio.com
Puertos 80/443 cerrados: Let's Encrypt necesita acceso
Límite de Let's Encrypt: 5 certificados/dominio/semana

Solución:

# Forzar renovación (si Traefik usa acme.json)
docker exec traefik rm /acme.json
docker restart traefik

Con NPM

Solución:

NPM → SSL Certificates
Encuentra tu certificado
Opciones (⋮) → Renew Certificate

Si falla:

Verifica DNS
Verifica puertos 80/443 abiertos
Intenta con DNS Challenge en lugar de HTTP Challenge

Mixed Content (HTTP en HTTPS)

Síntoma: Elementos de la página no cargan, errores de seguridad en consola

Solución:

# Verificar que DOMAIN usa https://
docker compose exec vaultwarden env | grep DOMAIN

# Debe ser: DOMAIN=https://vaultwarden.tudominio.com
# NO: DOMAIN=http://vaultwarden.tudominio.com

💾 Problemas con Base de Datos

Database is Locked

Síntoma: Error al crear/modificar entradas

Causa: SQLite bajo mucha carga concurrente

Solución:

# Aumentar timeout de DB
# Añadir a variables de entorno
DATABASE_MAX_CONNS=10

Para instalaciones grandes (>200 usuarios), considera migrar a PostgreSQL.

Database Corruption

Síntoma: Errores al leer datos, contenedor que crashea

Diagnóstico:

# Verificar integridad
docker run --rm -v vaultwarden_data:/data \
  nouchka/sqlite3 sqlite3 /data/db.sqlite3 "PRAGMA integrity_check;"

Solución:

# 1. Detener Vaultwarden
docker compose stop vaultwarden

# 2. Backup de la DB corrupta
docker run --rm -v vaultwarden_data:/data -v ~/:/backup alpine \
  cp /data/db.sqlite3 /backup/db.sqlite3.corrupted

# 3. Intentar reparación
docker run --rm -v vaultwarden_data:/data \
  nouchka/sqlite3 sqlite3 /data/db.sqlite3 ".recover" | \
  sqlite3 /data/db-recovered.sqlite3

# 4. Si la reparación funciona
docker run --rm -v vaultwarden_data:/data alpine \
  sh -c "mv /data/db.sqlite3 /data/db.sqlite3.broken && mv /data/db-recovered.sqlite3 /data/db.sqlite3"

# 5. Si todo falla, restaurar desde backup
# Ver: Backup y Restauración

🧩 Problemas con Clientes

Extensión del Navegador No Conecta

Síntomas: "Unable to connect to server"

Soluciones:

Verificar URL del servidor: https://vaultwarden.tudominio.com (sin /admin, sin barra final)
Verificar que HTTPS funciona desde navegador
Limpiar caché de la extensión
Reinstalar extensión como último recurso

App Móvil No Sincroniza

Causas comunes:

WebSocket no funciona (ver sección WebSocket arriba)
App en modo offline
Cuenta bloqueada o sesión expirada

Solución:

Cerrar sesión en la app
Volver a iniciar sesión
Verificar WebSocket: debe sincronizar al instante

CLI de Bitwarden Falla

Error: Invalid master password

Solución:

# Verificar configuración del servidor
bw config server https://vaultwarden.tudominio.com

# Ver config actual
bw config server

# Logout y login fresh
bw logout
bw login usuario@email.com

📊 Problemas de Rendimiento

Vaultwarden Muy Lento

Diagnóstico:

# Uso de recursos
docker stats vaultwarden --no-stream

# Si CPU >80% o RAM alta, posibles causas:
# 1. Base de datos muy grande
# 2. Muchos usuarios concurrentes
# 3. Iconos descargándose constantemente

Soluciones:

# 1. Deshabilitar iconos si no son necesarios
ICON_SERVICE=none

# 2. Aumentar límite de workers
ROCKET_WORKERS=20

# 3. Considerar PostgreSQL para >500 usuarios

Logs Creciendo Mucho

Síntoma: Disco lleno por /var/lib/docker/volumes/vaultwarden_data/_data/vaultwarden.log

Solución:

# Rotar logs manualmente
docker compose exec vaultwarden sh -c "truncate -s 0 /data/vaultwarden.log"

# O deshabilitar logs completamente
# Eliminar de docker-compose.yml:
# LOG_FILE: /data/vaultwarden.log

🆘 Comandos de Emergencia

Reset Completo (PELIGRO)

⚠️ Esto borra TODOS los datos:

docker compose down -v
docker volume rm vaultwarden_data
docker compose up -d

Acceso de Emergencia a la DB

# Entrar al contenedor
docker compose exec vaultwarden sh

# Abrir DB
sqlite3 /data/db.sqlite3

# Comandos útiles:
.tables                    # Ver tablas
SELECT * FROM users;       # Ver usuarios
.schema users              # Ver estructura de tabla
.quit                      # Salir

Exportar Todas las Contraseñas (Recuperación)

Desde la interfaz web:

Login → Tools
Export Vault
Master Password → Confirmar
File Format: JSON o CSV
Download

⚠️ El archivo descargado está sin cifrar. Elimínalo después de la recuperación.

📖 Recursos Adicionales

🔧 Obtener Ayuda

Si ninguna solución funcionó:

Revisa logs completos: docker compose logs vaultwarden > logs.txt
Documenta el problema: Qué intentaste, qué error ves

Prepara información del sistema:

docker --version
docker compose version
docker compose config

Busca en GitHub Issues: Probablemente alguien ya tuvo el mismo problema

Última actualización: Diciembre 2025

💡 Tip: El 90% de problemas se resuelven con: docker compose down && docker compose up -d después de verificar la configuración.

Solución de Problemas

🔍 Diagnóstico General

🚫 Contenedor No Inicia

Síntoma

Diagnóstico

Causas Comunes

1. Variable de Entorno Faltante

2. Puerto Ya en Uso

3. Volumen Corrupto

4. Permisos Incorrectos

🌐 No Puedo Acceder a la Web

Síntoma

Diagnóstico Paso a Paso

1. Verificar Contenedor

2. Verificar Red

3. Verificar Proxy

4. Verificar DNS

5. Verificar Firewall

Soluciones Específicas

Error 502 Bad Gateway

Error 503 Service Unavailable

Error 404 Not Found (con Traefik)

🔐 Problemas de Login

No Puedo Iniciar Sesión

Causa 1: Contraseña Maestra Incorrecta

Causa 2: Email No Verificado

Causa 3: 2FA Perdido

Session Expirada Constantemente

🔌 WebSocket No Funciona

Síntoma

Diagnóstico

Soluciones por Configuración

Con Traefik

Con NPM

Probar WebSocket

📧 Problemas con Email (SMTP)

Emails No Se Envían

Diagnóstico

Causas Comunes

1. Host o Puerto Incorrectos

2. SMTP_SECURITY Incorrecto

3. Credenciales Incorrectas

4. Firewall Bloqueando Puerto SMTP

Probar SMTP desde el Panel de Administración

🔒 Problemas con Certificados SSL

Certificado Inválido o Autofirmado

Con Traefik

Con NPM

Mixed Content (HTTP en HTTPS)

💾 Problemas con Base de Datos

Database is Locked

Database Corruption

🧩 Problemas con Clientes

Extensión del Navegador No Conecta

App Móvil No Sincroniza

CLI de Bitwarden Falla

📊 Problemas de Rendimiento

Vaultwarden Muy Lento

Logs Creciendo Mucho

🆘 Comandos de Emergencia

Reset Completo (PELIGRO)

Acceso de Emergencia a la DB

Exportar Todas las Contraseñas (Recuperación)

📖 Recursos Adicionales

🔧 Obtener Ayuda