Errores Comunes y Troubleshooting

Problemas de arranque

Error: exit code 127 en build de Render

Causa: NODE_ENV=production hace que Render no instale devDependencies (necesarias para compilar TypeScript).

Solucion: Usar yarn build:render como build command, que fuerza la instalacion de devDependencies.

Error: Cannot find module 'dist/src/main'

Causa: El proyecto no se compilo antes de intentar arrancar en modo produccion.

Solucion: Ejecutar yarn build primero, o usar yarn start:dev para desarrollo.

Error de conexion a MySQL

Causa: Credenciales incorrectas o MySQL no esta corriendo.

Checklist:

1. Verificar que MySQL esta corriendo en el puerto esperado
2. Verificar DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_NAME en .env
3. Verificar que la base de datos existe: CREATE DATABASE IF NOT EXISTS boost_crm;

Problemas de autenticacion

JWT invalido o expirado

Causa: El token JWT tiene una expiracion de 8 horas. Despues de ese tiempo, es necesario re-autenticarse.

Solucion: Hacer login nuevamente. Si el problema persiste, verificar que JWT_SECRET es el mismo en todos los entornos.

Login falla con “invalid credentials”

Checklist:

1. Verificar que el usuario existe en la tabla users
2. Verificar que el entity_id es correcto
3. Si es primer login con bootstrap: verificar que AUTH_ALLOW_FIRST_LOGIN_PASSWORD_BOOTSTRAP=true
4. Verificar que la API key de Zauru es valida (para bootstrap)

Cambio de entidad falla

Causa: El usuario no tiene suscripcion para la entidad destino.

Solucion: Crear una suscripcion en la tabla subscriptions para ese user_id + entity_id.

Problemas con Zauru

“Zauru session not found”

Causa: No se ha reconciliado la sesion de Zauru para este usuario+entidad.

Solucion: Llamar a POST /api/auth/zauru-session/sync o re-hacer login.

Datos de catalogo vacios o desactualizados

Checklist:

1. Verificar que ZAURU_ENV apunta al entorno correcto
2. Verificar que la sesion Zauru tiene un JWT GraphQL valido
3. Si Pulpito esta habilitado, el cache puede estar sirviendo datos stale – esperar al refresh o reiniciar
4. Verificar manualmente con las requests en BoostAPI/docs/zauru-catalog-debug.http

Error de GraphQL de Zauru

Causa: JWT de GraphQL expirado o invalido.

Solucion: Forzar sync de sesion: POST /api/auth/zauru-session/sync

Problemas de interacciones

Webhooks no llegan

Checklist:

1. Verificar que COMMUNICATIONS_BASE_URL es correcto
2. Verificar que el webhook esta registrado (usar command palette: POST /api/interactions/communications/webhook-sync)
3. En dev: verificar que el tunnel esta activo (COMMUNICATIONS_DEV_TUNNEL_ENABLED=true)
4. Verificar logs del servicio de Communications

Mensajes no se envian

Checklist:

1. Verificar que la sesion de Communications esta activa
2. Verificar que COMMUNICATIONS_API_KEY es valida
3. Verificar que la conversacion tiene un external_chat_id valido
4. Para WhatsApp: verificar que el template esta aprobado (si aplica)

WebSocket no conecta

Checklist:

1. Verificar que el JWT es valido
2. El namespace es /interactions (no la raiz)
3. Enviar token en handshake: auth: { token: "[REDACTED]..." }
4. Verificar CORS si se conecta desde un dominio diferente

Problemas de media

Upload falla con presigned URL

Checklist:

1. Verificar credenciales AWS: AWS_ACCES_KEY_ID_AOC, AWS_SECRET_ACCESS_KEY_AOC
2. Verificar que el bucket AWS_S3_BUCKET existe y tiene los permisos correctos
3. La presigned URL tiene un timeout – subir el archivo antes de que expire

Media no se procesa

Causa: Si MEDIA_INLINE_WORKER_ENABLED=false, se necesita correr el worker por separado.

Solucion: Correr yarn media:worker en un proceso separado, o activar MEDIA_INLINE_WORKER_ENABLED=true.

Problemas de CORS

Request bloqueado por CORS

Checklist:

1. Verificar que el origen esta en CORS_ALLOWED_ORIGINS
2. En dev, localhost se permite automaticamente
3. Si el frontend tiene path en la URL, verificar que el backend normaliza correctamente
4. Para debugging, temporalmente agregar * a CORS_ALLOWED_ORIGINS

Problemas de seeds

Seed falla con “duplicate entry”

Causa: La seed ya se corrio antes y los datos ya existen.

Solucion: Las seeds son idempotentes en su mayoria. Si no, limpiar las tablas afectadas manualmente.

Seeds de produccion no corren

Causa: Las seeds de produccion corren desde dist/scripts/*.js, no desde TypeScript.

Solucion: Compilar primero con yarn build, luego correr la seed.

Herramientas de debug

Herramienta	Uso
Swagger (/api)	Testing interactivo de endpoints
.http files	Requests de ejemplo para VS Code REST Client
zauru-catalog-debug.http	Debug de datos de catalogo Zauru
zauru-facturas-debug.http	Debug de facturas Zauru
zauru-pagos-debug.http	Debug de pagos Zauru
zauru-company-debug.http	Debug de empresas Zauru
essss.http	Requests variados de testing

Referencia privada: Ver los archivos .http en la raiz de BoostAPI/ y la documentacion en BoostAPI/docs/ para mas detalles de troubleshooting.