Diagnóstico

Índice / Index · English

Traducción de docs/en/operations/troubleshooting.md, que es el original. Si discrepan, manda el inglés.

Estos casos vienen de las guardas de arranque que hay hoy, de los scripts, o de fallos que ya aparecieron construyendo el repositorio.

#La API se cierra al arrancar con ADMIN_TOKEN is required

#Causa

RolesGuard.onModuleInit() se niega a arrancar sin un token de al menos 16 caracteres. Ese token crea la primera administradora y mueve la CI y la semilla.

#Arreglo

Ponlo en el entorno del proceso de la API. En PowerShell:

$env:ADMIN_TOKEN = 'cambia-esto-por-al-menos-16-caracteres'
npm run dev:api

El NUXT_ADMIN_TOKEN del servidor de la consola y el ADMIN_TOKEN de la semilla tienen que coincidir cuando usen la credencial raíz.

#La consola arranca pero nadie puede entrar

#Causa

Una base recién creada no tiene personas. ADMIN_TOKEN no es una contraseña de la consola y no crea a nadie automáticamente.

#Arreglo

Corre npm run admin:create contra la API en marcha; pregunta dirección y contraseña, y verifica la cuenta entrando con ella. npm run seed también crea una, junto con los datos de demostración. Las dos están en Primeros pasos. Comprueba además que NUXT_SESSION_PASSWORD (o el SESSION_PASSWORD de Compose) tenga al menos 32 caracteres.

#Olvidé la contraseña del administrador

Si la cuenta ya existe, usa npm run password:reset -- --email usuario@example.test desde la raíz del repositorio, con tu correo y la API en marcha. Pregunta la nueva contraseña en modo oculto y cierra las sesiones anteriores. Consulta Restablecer contraseña para los requisitos y las opciones.

#Las pruebas de integración salen saltadas

#Síntoma

Vitest da por saltados los specs de test/integration/ mientras las unitarias pasan.

#Causa

El arnés comprueba DATABASE_URL a propósito. No va a adivinar una base y arriesgarse a escribir en la equivocada.

#Arreglo

Levanta un PostgreSQL desechable y define DATABASE_URL antes de npm test. Ver Pruebas. No apuntes la suite a una base con datos que te importen.

#Docker no conecta con el motor

#Síntoma

docker version enseña el cliente pero no conecta con el motor Linux de Docker Desktop ni con la tubería con nombre.

#Causa

Los servicios de Docker Desktop o de WSL no están corriendo. Es también la razón de que la validación local histórica de HANDOFF.md no pudiera ejercitar Compose.

#Arreglo

Arranca Docker Desktop y espera a que docker version informe de cliente y servidor. Después:

docker compose config
docker compose up --build --wait

La CI actual ejercita la pila entera en Linux aunque una estación Windows no pueda arrancar su motor local.

#El typecheck o el build imprimen avisos de dependencias de Vue o Nuxt

#Síntoma

npm run typecheck puede imprimir vue-router/volar/sfc-route-blocks ERR_PACKAGE_PATH_NOT_EXPORTED, y un build en versiones nuevas de Node puede imprimir avisos DEP0155 de paquetes de Vue o PrimeUI.

#Qué significa

Vienen del grafo de dependencias actual de Nuxt y Vue. En la última validación del repositorio, el typecheck y las tres compilaciones salieron correctamente. Toma el código de salida como el resultado inmediato, pero no silencies los avisos: alinear dependencias debería quitarlos en un mantenimiento futuro.

#Un escenario JSON cambiado no hace nada

#Causa

Los escenarios propios en ejecución salen del generado apps/api/src/modules/scenarios/default-scenarios.ts, no del JSON directamente.

#Arreglo

npm run scenario:compile

El typecheck, las pruebas y el build lo corren solos, pero el proceso de desarrollo de la API no tiene un gancho previo de escenarios. Reinícialo después de regenerar.

No edites el TypeScript generado; la siguiente compilación lo pisa.

#Los webhooks se quedan en scheduled

#Comprobaciones

1. Confirma que el worker está corriendo; la API a propósito nunca abre una cola. El worker imprime [queue] driver: … en la línea con la que arranca.
2. Confirma que lo que ese driver necesita responde — REDIS_URL para bullmq, MONGO_URL para mongo. El de por defecto, postgres, no necesita nada más. run-local.bat doctor informa del driver y de su dependencia juntos, y vale la pena hacerlo antes que nada: el script comprobaba un puerto de Redis y arrancaba un worker que marcaba otro.
3. Pon RUNTIME_OUTBOUND_ENABLED=true en el proceso del worker.
4. Comprueba que el host del callback resuelve a una direccion publica. Si es interno a proposito -- una maquina de tu red, localhost -- ponlo en WEBHOOK_ALLOWED_HOSTS, que es la lista de excepciones a esa regla.
5. Desde un contenedor, usa host.docker.internal para un callback que corra en el anfitrión; localhost dentro del contenedor es el contenedor. Fuera de uno, al revés: host.docker.internal resuelve a un adaptador de Docker en el que no escucha nadie cuando Docker no está en marcha.

La fila del outbox es durable. Un fallo temporal del transporte no borra la notificación que se debe; el despachador reintenta las filas rancias.

#Un webhook llega más de una vez

Es válido. La entrega es al menos una vez, y los escenarios pueden pedir duplicados a propósito. La integración que recibe tiene que deduplicar con su estrategia normal. Mira el evento y sus intentos en la consola antes de tratar el duplicado como un defecto del worker.

#Un filtro de listado se ignora o se rechaza

La forma soportada es:

?page=2&pageSize=25&sort=-createdAt,name&search=ana&filter[state]=captured

Cada endpoint tiene su lista blanca. Un sort o un filter no declarado es un 400, no un parámetro ignorado en silencio. Si en un arnés Nest propio parece que se ignoran todos los filtros, comprueba que llama a configureApp(); esa función activa el parser extendido de query de Express y la comparten producción y el arnés oficial. Ver el contrato de listados.

#Las peticiones del SDK de Mercado Pago no se pueden redirigir al emulador

Es un límite de fidelidad documentado, no una variable de entorno que falte. El SDK instalado guarda el host de producción en un campo estático no configurable. Se usa su validador de webhooks, pero la compatibilidad de las peticiones se prueba con la suite de conformidad del propio emulador. Ver Fidelidad de Mercado Pago.

#Stripe devuelve provider_operation_not_found en una actualización

POST /v1/payment_intents/{id} no está enrutado a propósito. Mapear la actualización sobre la confirmación intentaría un pago que quien llama sólo quería editar. Esa carencia está en Fidelidad de Stripe.

#Las migraciones parecen no correr desde la raíz

Usa el comando de la raíz, que lee .env y .env.local, compila la API si hace falta y espera a PostgreSQL:

npm run migrate

El directorio de migraciones está anclado al fichero de configuración de MikroORM, para que la ejecución desde fuente y desde compilado usen la misma carpeta migrations/. En Compose, el contenedor de la API corre node dist/cli/migrate.js antes de levantar HTTP, así que ahí casi nunca hace falta migrar a mano.

#Falla el comando de migración o el worker de desarrollo

Las migraciones y el worker corren desde dist/, nunca con tsx: las entidades llevan los tipos de sus propiedades en emitDecoratorMetadata, que esbuild no emite, así que bajo tsx no se descubre ninguna entidad. Por eso start:worker:dev no puede funcionar.

npm run migrate
npm run start:worker --workspace @payment-emulator/api

Configura antes las variables de base de datos y operador. La migración aplica los cambios pendientes a la base elegida; usa una base desechable para las pruebas. npm run migrate -- --fresh vacía una deshaciendo todas las migraciones y volviéndolas a aplicar, sin superusuario y sin psql.