# Opción 1: Cambiar permisos desde host
sudo chown -R 1000:1000 /var/lib/docker/volumes/uptime-kuma_data

# Opción 2: Desde contenedor
docker compose run --rm uptime-kuma chown -R 1000:1000 /app/data

Error: "Database locked"

Causa: Múltiples contenedores intentando acceder a kuma.db.

Solución:

# Listar todos los contenedores uptime-kuma
docker ps -a | grep uptime-kuma

# Detener todos
docker stop $(docker ps -a -q --filter name=uptime-kuma)

# Eliminar duplicados
docker rm $(docker ps -a -q --filter name=uptime-kuma)

# Reiniciar limpio
docker compose up -d uptime-kuma

Error: "Cannot find module..."

Causa: Imagen corrupta o actualización fallida.

Solución:

# Eliminar imagen y volver a descargar
docker compose down
docker rmi louislam/uptime-kuma:2
docker compose pull
docker compose up -d

No se Puede Acceder a la Interfaz

Error 502 Bad Gateway (Traefik)

Verificar contenedor activo:

docker compose ps
# Debe mostrar: Up

Verificar red proxy:

docker network inspect proxy | grep uptime-kuma
# Debe aparecer el contenedor

Verificar labels de Traefik:

docker inspect uptime-kuma | grep -A 10 Labels
# Verificar:
# - traefik.enable=true
# - loadbalancer.server.port=3001
# - rule=Host(`...`)

Verificar logs de Traefik:

docker logs traefik | grep uptime-kuma

Error 502 Bad Gateway (NPM)

Verificar Forward Port: Debe ser 3001, no 80.

Verificar hostname: Debe ser uptime-kuma (nombre del contenedor).

Verificar red: Ambos contenedores deben estar en red proxy.

docker network inspect proxy | grep -E "uptime-kuma|nginx-proxy-manager"

Certificado SSL no se Genera

Verificar DNS:

nslookup uptime.example.com
# Debe devolver la IP de tu servidor

Verificar puertos abiertos:

# En el host
ss -tlnp | grep :80
ss -tlnp | grep :443

Verificar logs de Let's Encrypt (Traefik):

docker logs traefik 2>&1 | grep -i "letsencrypt\|acme"

Monitores Reportan "Down" Incorrectamente

Falsos Positivos

Ajustar configuración:

Editar monitor
Aumentar Retries: de 3 a 5
Aumentar Heartbeat Interval: de 60 a 120 segundos
Aumentar Timeout: de 48 a 60 segundos
Save

Verificar desde Contenedor

Probar conectividad desde dentro del contenedor Uptime Kuma:

# HTTP
docker compose exec uptime-kuma wget -O- https://example.com

# Ping
docker compose exec uptime-kuma ping -c 4 example.com

# DNS
docker compose exec uptime-kuma nslookup example.com

# TCP Port
docker compose exec uptime-kuma nc -zv example.com 443

Error: "Invalid URL"

Causa: URL mal formada.

Correcto:

https://example.com ✅
https://example.com:443 ✅
https://example.com/path ✅

Incorrecto:

example.com ❌ (falta protocolo)
https:// ❌ (falta dominio)

Error: "Keyword not found"

Causa: La página no contiene el keyword esperado.

Verificar:

# Descargar página y buscar keyword
docker compose exec uptime-kuma wget -qO- https://example.com | grep "keyword"

Si no aparece:

El keyword es incorrecto
La página cambió
La página requiere autenticación

Notificaciones no Funcionan

Error: "Bad Request: chat not found"

Causa: Chat ID incorrecto.

Solución:

Obtener Chat ID correcto:
- Usuario: Número positivo (123456789)
- Grupo: Número negativo (-987654321)
Usar @userinfobot para verificar ID

Error: "Unauthorized"

Causa: Bot token inválido.

Solución:

Verificar token con @BotFather
Enviar /mybots → Seleccionar bot → API Token

Discord

Error: "Unknown Webhook"

Causa: Webhook eliminado o URL incorrecta.

Solución:

Verificar webhook existe en Discord
Regenerar webhook si es necesario

Email (SMTP)

Error: "EAUTH: authentication failed"

Causa: Usuario/password incorrecto.

Gmail:

Usar App Password, no contraseña de cuenta
Generar en: https://myaccount.google.com/apppasswords

Outlook/Office365:

Usar autenticación moderna (OAuth2) no soportada
Alternativa: Usar SMTP relay externo (SendGrid, Mailgun)

Error: "ETIMEDOUT"

Causa: Firewall bloquea puerto SMTP.

Solución:

# Verificar conectividad
docker compose exec uptime-kuma nc -zv smtp.gmail.com 587

WebSockets no Funcionan

Síntomas

Interfaz no se actualiza en tiempo real
Necesitas refrescar página (F5) para ver cambios
Consola del navegador (F12) muestra: WebSocket connection failed

Traefik

Traefik soporta WebSockets automáticamente. Si hay problemas:

Añadir headers explícitos (raro):

labels:
  - traefik.http.middlewares.uptime-ws.headers.customrequestheaders.Connection=Upgrade
  - traefik.http.middlewares.uptime-ws.headers.customrequestheaders.Upgrade=websocket
  - traefik.http.routers.uptime-kuma.middlewares=uptime-ws

NPM

Verificar checkbox:

✅ Websockets Support DEBE estar habilitado

Si está habilitado y no funciona:

Editar Proxy Host

Advanced → Custom Nginx Configuration:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Base de Datos Corrupta

Síntomas

Error al iniciar: SQLITE_CORRUPT
Monitores desaparecen
Datos inconsistentes

Verificar Integridad

docker compose exec uptime-kuma sqlite3 /app/data/kuma.db "PRAGMA integrity_check;"

Si devuelve algo diferente a "ok", la base de datos está corrupta.

Intentar Reparar

# Dump y recrear
docker compose exec uptime-kuma sqlite3 /app/data/kuma.db ".dump" > kuma-dump.sql
docker compose exec uptime-kuma sqlite3 /app/data/kuma-new.db < kuma-dump.sql

# Reemplazar
docker compose stop uptime-kuma
docker compose cp kuma-new.db uptime-kuma:/app/data/kuma.db
docker compose start uptime-kuma

Restaurar desde Backup

Si reparación falla:

docker compose stop uptime-kuma
docker compose cp ./backup/kuma-latest.db uptime-kuma:/app/data/kuma.db
docker compose start uptime-kuma

Status Page no Carga

Error 404

Causa: Slug incorrecto en URL.

Verificar:

Status Pages → Ver slug configurado
URL debe ser: https://uptime.example.com/status/{slug}

Status Page Pública no Accesible

Verificar configuración:

Editar Status Page
✅ Public debe estar habilitado
Save

CSS Personalizado no Aplica

Limpiar cache:

Chrome/Edge: Ctrl + Shift + R
Firefox: Ctrl + F5

Logs de Depuración

Habilitar Logs Detallados

Uptime Kuma no tiene modo verbose nativo, pero puedes:

# Ver logs en tiempo real con timestamps
docker compose logs -f --timestamps uptime-kuma

# Ver logs de Docker daemon
journalctl -u docker -f | grep uptime-kuma

Exportar Logs

# Últimas 1000 líneas
docker compose logs --tail=1000 uptime-kuma > uptime-kuma-logs.txt

# Todos los logs
docker compose logs uptime-kuma > uptime-kuma-full-logs.txt

Performance y Recursos

Alto Uso de CPU

Causa: Demasiados monitores con interval muy bajo.

Solución:

Aumentar Heartbeat Interval de monitores no críticos
Reducir número de monitores
Usar monitor DNS o Ping en lugar de HTTP para checks simples

Alto Uso de RAM

Causa: Retención de datos muy larga + muchos monitores.

Solución:

Settings → General → Keep Data: Reducir de 180 a 90 días

Vacuumar base de datos:

docker compose exec uptime-kuma sqlite3 /app/data/kuma.db "VACUUM;"

Base de Datos Muy Grande

Verificar tamaño:

docker compose exec uptime-kuma ls -lh /app/data/kuma.db

Reducir tamaño:

# Reducir retención en Settings
# Luego vacuumar
docker compose exec uptime-kuma sqlite3 /app/data/kuma.db "VACUUM;"

Solución de Problemas

Contenedor no Inicia

Verificar Logs

Error: "EACCES: permission denied"

Error: "Database locked"

Error: "Cannot find module..."

No se Puede Acceder a la Interfaz

Error 502 Bad Gateway (Traefik)

Error 502 Bad Gateway (NPM)

Certificado SSL no se Genera

Monitores Reportan "Down" Incorrectamente

Falsos Positivos

Verificar desde Contenedor

Error: "Invalid URL"

Error: "Keyword not found"

Notificaciones no Funcionan

Telegram

Discord

Email (SMTP)

WebSockets no Funcionan

Síntomas

Traefik

NPM

Base de Datos Corrupta

Síntomas

Verificar Integridad

Intentar Reparar

Restaurar desde Backup

Status Page no Carga

Error 404

Status Page Pública no Accesible

CSS Personalizado no Aplica

Logs de Depuración

Habilitar Logs Detallados

Exportar Logs

Performance y Recursos

Alto Uso de CPU

Alto Uso de RAM

Base de Datos Muy Grande

Soporte

Navegación

🏠 Home

🚀 Despliegue

⚙️ Configuración

🔧 Mantenimiento