Troubleshooting Guide

Overview

Guía de diagnóstico y resolución de problemas comunes en Orchestrator, Sevastopol y PostgreSQL.

---

🔴 Orchestrator No Responde

Síntomas

• curl http://localhost:8000/health no responde
• Frontend muestra “Network Error”
• Logs muestran timeouts

Diagnóstico

# 1. Verificar estado del proceso
pm2 status orchestrator

# 2. Ver logs de error
pm2 logs orchestrator --err --lines 50

# 3. Verificar puerto
lsof -i :8000

Soluciones

Causa	Solución
Proceso muerto	pm2 restart orchestrator
Puerto en uso	kill -9 $(lsof -t -i:8000) y reiniciar
OOM (Out of Memory)	Aumentar RAM o reducir max_connections
DB connection failed	Ver sección “PostgreSQL No Conecta”

---

🔴 PostgreSQL No Conecta

Síntomas

• Error: connect ECONNREFUSED 127.0.0.1:5432
• FATAL: connection refused

Diagnóstico

# 1. Verificar servicio PostgreSQL
sudo systemctl status postgresql

# 2. Verificar si está escuchando
pg_isready

# 3. Verificar logs
sudo tail -50 /var/log/postgresql/postgresql-16-main.log

Soluciones

Causa	Solución
Servicio caído	sudo systemctl start postgresql
Max connections	Aumentar max_connections en postgresql.conf
pg_hba.conf	Verificar que permite conexiones locales
Disco lleno	Liberar espacio en disco

---

🟡 Queries Lentas

Síntomas

• Timeouts en API (> 30s)
• Dashboard carga lento
• CPU PostgreSQL alto

Diagnóstico

-- Queries actualmente corriendo
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE state = 'active'
ORDER BY duration DESC;

-- Top queries lentas (requiere pg_stat_statements)
SELECT query, calls, mean_exec_time::numeric(10,2) as mean_ms
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

Soluciones

Causa	Solución
Missing index	Crear índice en columnas filtradas
Table bloat	VACUUM ANALYZE <table>
Full table scan	Revisar EXPLAIN ANALYZE
Lock contention	Ver sección “Deadlocks”

Ejemplo - Agregar índice faltante:

-- Si query filtra por employee_id frecuentemente
CREATE INDEX CONCURRENTLY idx_contracts_employee
ON contracts(employee_id);

---

🟡 Error de Autenticación

Síntomas

• “Invalid credentials” en login
• “Token expired”
• 401 Unauthorized

Diagnóstico

# Verificar JWT_SECRET configurado
echo $JWT_SECRET | wc -c
# Debe ser > 32 caracteres

# Verificar que cookies se envían
curl -v --cookie-jar - http://localhost:8000/api/command/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

Soluciones

Causa	Solución
JWT_SECRET vacío	Configurar en .env.production
Token expirado	Relogin (JWT expira en 24h)
Cookie no persiste	Verificar SameSite y Secure flags
Usuario desactivado	UPDATE users SET active=true WHERE email='...'

---

🟡 Error de Tenant

Síntomas

• “Tenant not found”
• “Schema does not exist”
• Datos mezclados entre clientes

Diagnóstico

-- Verificar que tenant existe
SELECT * FROM central.tenants WHERE id = '<TENANT_ID>';

-- Verificar que schema existe
SELECT nspname FROM pg_namespace WHERE nspname = 'tenant_<ID>';

-- Verificar search_path actual en sesión
SHOW search_path;

Soluciones

Causa	Solución
Tenant no existe	Crear tenant via admin
Schema borrado	Restore from backup
search_path incorrecto	Verificar middleware de tenant
Header X-Tenant-ID faltante	Verificar frontend envía header

---

🟡 Build de Sevastopol Falla

Síntomas

• npm run build falla
• Errores de TypeScript
• MDX parsing errors

Diagnóstico

# Limpiar cache
rm -rf node_modules/.vite
rm -rf dist

# Reinstalar dependencias
rm -rf node_modules
npm ci

# Build con verbose
npm run build -- --verbose

Soluciones

Error	Solución
MDX parsing error	Escapar caracteres especiales (<, >, {, })
TypeScript error	Corregir tipos o usar // @ts-ignore temporal
Memory heap	NODE_OPTIONS="--max-old-space-size=4096" npm run build
Dependency conflict	Borrar lockfile y regenerar

---

🟡 Errores de CORS

Síntomas

• “Access-Control-Allow-Origin” error en browser
• Requests bloqueados en frontend
• Preflight OPTIONS fallando

Diagnóstico

# Verificar headers de respuesta
curl -v -X OPTIONS http://localhost:8000/api/query/employees \
  -H "Origin: http://localhost:4321" \
  -H "Access-Control-Request-Method: GET"

Soluciones

Causa	Solución
Origin no permitido	Agregar origin a lista de CORS
Credentials no permitidas	Access-Control-Allow-Credentials: true
Headers no permitidos	Agregar headers a Allow-Headers
Nginx proxy	Verificar config de proxy_set_header

Config ejemplo (Orchestrator):

app.use(
  cors({
    origin: ["http://localhost:4321", "https://app.nostromo.cl"],
    credentials: true,
    allowedHeaders: ["Content-Type", "Authorization", "X-Tenant-ID"],
  }),
);

---

🟡 Memory Leak

Síntomas

• RAM de proceso crece constantemente
• pm2 monit muestra memoria subiendo
• OOM kills en logs del sistema

Diagnóstico

# Monitorear memoria en tiempo real
pm2 monit

# Ver memoria del proceso
ps aux | grep node

# Generar heap dump (Node.js)
kill -USR2 <PID>

Soluciones

Causa	Solución
Event listeners sin cleanup	Revisar removeEventListener
DB connections no cerradas	Verificar pool.release()
Cache sin límite	Agregar LRU cache con max size
Circular references	Usar WeakMap/WeakRef

Configuración de restart automático:

# PM2 - restart cuando excede 500MB
pm2 start dist/server.js --name orchestrator --max-memory-restart 500M

---

🟠 Deadlocks en PostgreSQL

Síntomas

• “deadlock detected” en logs
• Transactions colgadas
• Queries que nunca terminan

Diagnóstico

-- Ver locks actuales
SELECT
    blocked.pid as blocked_pid,
    blocked.query as blocked_query,
    blocking.pid as blocking_pid,
    blocking.query as blocking_query
FROM pg_stat_activity blocked
JOIN pg_locks blocked_locks ON blocked.pid = blocked_locks.pid
JOIN pg_locks blocking_locks
    ON blocked_locks.locktype = blocking_locks.locktype
    AND blocked_locks.relation = blocking_locks.relation
    AND blocked_locks.pid != blocking_locks.pid
JOIN pg_stat_activity blocking ON blocking_locks.pid = blocking.pid
WHERE NOT blocked_locks.granted;

Soluciones

Causa	Solución
Transaction larga	Reducir tamaño de transactions
Lock order inconsistente	Ordenar acceso a tablas consistentemente
Lock timeout bajo	SET lock_timeout = '10s'
Query bloqueando	SELECT pg_cancel_backend(<PID>)

---

🟠 Disco Lleno

Síntomas

• “No space left on device”
• PostgreSQL read-only mode
• Logs no se escriben

Diagnóstico

# Ver uso de disco
df -h

# Encontrar archivos grandes
du -sh /* | sort -rh | head -20

# Ver logs grandes
du -sh /var/log/*

Soluciones

Causa	Solución
Logs grandes	Rotar logs: logrotate -f /etc/logrotate.conf
WAL acumulado	pg_switch_wal() + verificar replicación
Backups locales	Mover a storage remoto
Core dumps	Borrar /var/crash/*

---

Herramientas de Diagnóstico

Logs

# Orchestrator
pm2 logs orchestrator --lines 100

# PostgreSQL
sudo tail -f /var/log/postgresql/postgresql-16-main.log

# Nginx
sudo tail -f /var/log/nginx/error.log

# System
sudo journalctl -u orchestrator -f

Métricas

# CPU y memoria
htop

# Disco I/O
iotop

# Network
nethogs

# PostgreSQL stats
psql -c "SELECT * FROM pg_stat_activity;"

---

Contactos de Escalación

Nivel	Problema	Contacto
L1	Servicio caído	On-call engineer
L2	Data corruption	DBA team
L3	Security breach	Security team + management

---

Related Documentation

• Runbook: Recovery - Disaster recovery procedures
• Runbook: Backup - Backup y restore
• Infrastructure: PostgreSQL - Config de DB
• Infrastructure: Networking - Network config

---

Changelog

Fecha	Version	Cambios
2026-01-18	1.0	Guía inicial creada