Troubleshooting

Problemas comunes y sus soluciones. Consultar esta pagina antes de escalar un issue.

Docker: contenedor no arranca

Sintomas: El contenedor se reinicia en loop o sale con codigo de error.

# Ver logs del contenedor
docker logs zentto-api --tail 200
docker logs zentto-frontend --tail 200

# Ver estado
docker ps -a | grep zentto

Causas comunes:

• Archivo .env faltante o con variables incorrectas en /opt/zentto/
• Puerto ya en uso por otro proceso
• Imagen corrupta — hacer docker compose pull de nuevo
• Falta de espacio en disco — revisar con df -h y limpiar con docker image prune -af

CORS: errores en el navegador

Sintomas: Access-Control-Allow-Origin missing o valor incorrecto en respuestas de api.zentto.net.

Solucion:

• Verificar que Nginx tiene las directivas CORS con flag always (aplica incluso en errores 5xx)
• Verificar que el Origin de la request coincide con los patrones en zentto.conf
• Si Express y Nginx ambos envian headers CORS, hay duplicados — Nginx debe ocultar los del upstream con proxy_hide_header

# Probar CORS manualmente
curl -I -H "Origin: https://app.zentto.net" https://api.zentto.net/v1/health

# Verificar config de Nginx
nginx -t && nginx -s reload

PostgreSQL: conexion rechazada desde Docker

Sintomas: ECONNREFUSED 127.0.0.1:5432 o connection refused desde el contenedor API.

Solucion paso a paso:

1. Verificar que PG_HOST en .env.api sea 172.18.0.1 (gateway Docker), no localhost
2. Verificar regla UFW: ufw status | grep 5432
3. Verificar iptables: iptables -L DOCKER-USER -n | grep 5432
4. Verificar pg_hba.conf: debe tener host zentto_prod zentto_app 172.18.0.0/16 scram-sha-256
5. Recargar PostgreSQL: systemctl reload postgresql

# Agregar reglas si faltan
ufw allow from 172.18.0.0/16 to any port 5432
iptables -I DOCKER-USER -s 172.18.0.0/16 -p tcp --dport 5432 -j ACCEPT

# Probar conectividad desde el contenedor
docker exec zentto-api sh -c "nc -zv 172.18.0.1 5432"

SP retorna error

Sintomas: La API devuelve {"ok": false, "mensaje": "..."} o error 500.

Checklist:

• Verificar que el SP existe en el motor activo (DB_TYPE en .env)
• Verificar nombre exacto — SQL Server es case-insensitive pero PG es case-sensitive en nombres entre comillas
• Verificar tipos de parametros — BIT vs BOOLEAN, NVARCHAR vs VARCHAR
• Probar el SP directamente en la consola del motor correspondiente
• Revisar los logs de la API: docker logs zentto-api --tail 100

Frontend: build falla

Sintomas: Error de TypeScript o de dependencias al compilar una micro-app.

Solucion:

• Verificar tsconfig.json de la app — debe extender el config base
• Verificar que los paquetes compartidos (@zentto/shared-ui, @zentto/shared-api) estan correctamente referenciados en package.json
• Limpiar cache: rm -rf node_modules/.cache .next
• Reinstalar dependencias: rm -rf node_modules && npm ci
• Verificar que la version de Node.js sea 20.x

Deploy: falla en GitHub Actions

Sintomas: El workflow de deploy falla en algun step.

Sesion de usuario expira constantemente

Sintomas: El usuario es redirigido al login frecuentemente.

• Verificar que AUTH_SECRET es el mismo en .env.frontend y en GitHub Secrets
• Verificar que AUTH_TRUST_HOST=true esta configurado
• Verificar que NEXTAUTH_URL coincide con el dominio real (https://app.zentto.net)
• Revisar los buffers de Nginx — cookies JWT grandes necesitan proxy_buffer_size 64k

Comando rapido de diagnostico

# Estado completo del servidor
docker ps -a
docker exec zentto-frontend pm2 status
ufw status
systemctl status postgresql nginx
df -h
docker system df