🔧 Troubleshooting

Problemas Comunes y Soluciones

Desarrollo

Error: "Cannot find module '@/core/db'"

Causa: Path alias no configurado

Solución:

1. Verifica tsconfig.json:

   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }

2. Reinicia el servidor TypeScript en tu IDE
3. Ejecuta pnpm type-check para verificar

Error: "Prisma Client not generated"

Causa: Prisma Client no generado después de cambios en schema

Solución:

pnpm db:generate

Error: "Module not found" en tests

Causa: Vitest no encuentra módulos con path aliases

Solución:

1. Verifica vitest.config.ts:

   resolve: {
     alias: {
       '@': path.resolve(__dirname, './src'),
     },
   }

2. Reinicia los tests

Base de Datos

Error: "Unique constraint failed"

Causa: Intento de crear registro duplicado

Solución:

1. Verifica que no existe el registro:

   const existing = await db.model.findUnique({
     where: { uniqueField: value },
   });

2. Usa upsert en lugar de create si es apropiado

Error: "Foreign key constraint failed"

Causa: Referencia a registro inexistente

Solución:

1. Verifica que el registro referenciado existe
2. Verifica el orden de creación (crear dependencias primero)

Error: "Connection timeout"

Causa: Base de datos no accesible o credenciales incorrectas

Solución:

1. Verifica DATABASE_URL en .env.local
2. Verifica que Supabase está activo
3. Verifica firewall/red

Autenticación (Clerk)

Error: "Unauthorized" en Server Actions

Causa: Usuario no autenticado o sin permisos

Solución:

1. Verifica que el usuario está autenticado:

   const user = await getCurrentUser();
   if (!user) throw new Error('Unauthorized');

2. Verifica RBAC:

   requireRole(user, ['ORGANIZER', 'ADMIN']);

Error: "Clerk user not found"

Causa: Profile no sincronizado con Clerk

Solución:

1. Verifica que el webhook de Clerk está configurado
2. Crea el profile manualmente si es necesario:

   await db.profile.create({
     data: {
       userId: clerkUserId,
       email: email,
       name: name,
       role: 'PARTICIPANT',
     },
   });

Supabase Realtime

Error: "Supabase Realtime no configurado"

Causa: Variables de entorno faltantes

Solución:

1. Verifica .env.local:

   NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx

2. Reinicia el servidor

Error: "No se puede suscribir al canal"

Causa: RLS bloqueando o Realtime no habilitado

Solución:

1. Habilita Realtime en Supabase Dashboard → Database → Replication
2. Verifica políticas RLS
3. Verifica que el usuario está autenticado

No se actualiza automáticamente

Causa: Realtime no configurado correctamente

Solución:

1. Verifica conexión WebSocket en DevTools
2. Verifica que Realtime está habilitado
3. Revisa consola para errores

Server Actions

Error: "FormData is not defined"

Causa: Server Action ejecutándose en cliente

Solución:

1. Verifica que el archivo tiene 'use server' al inicio
2. Verifica que estás llamando desde un componente del servidor o con formAction

Error: "revalidatePath is not a function"

Causa: Import incorrecto

Solución:

import { revalidatePath } from 'next/cache';

Validaciones

Error: "Zod validation failed"

Causa: Datos no cumplen schema

Solución:

1. Revisa el error de Zod para ver qué campo falla
2. Verifica tipos de datos (dates, numbers, etc.)
3. Usa .parse() con try-catch para mejor debugging:

   try {
     const validated = schema.parse(data);
   } catch (error) {
     if (error instanceof z.ZodError) {
       console.error(error.errors);
     }
   }

Build y Deploy

Error: "Build failed" en Vercel

Causa: Variables de entorno faltantes o errores de TypeScript

Solución:

1. Verifica variables de entorno en Vercel Dashboard
2. Ejecuta pnpm build localmente para reproducir
3. Verifica logs de build en Vercel

Error: "Cron job not running"

Causa: Configuración incorrecta en vercel.json

Solución:

1. Verifica vercel.json:

   {
     "crons": [{
       "path": "/api/cron/update-hackathon-states",
       "schedule": "* * * * *"
     }]
   }

2. Verifica que la ruta existe y retorna 200
3. Verifica CRON_SECRET en variables de entorno

Performance

Aplicación lenta

Causa: Queries N+1 o falta de índices

Solución:

1. Usa include para cargar relaciones:

   await db.hackathon.findMany({
     include: {
       criteria: true,
       judges: true,
     },
   });

2. Agrega índices en Prisma schema:

   model Hackathon {
     @@index([status])
     @@index([organizerId])
   }

Tests lentos

Causa: Tests usando DB real o mocks ineficientes

Solución:

1. Usa mocks en lugar de DB real
2. Limpia datos eficientemente
3. Usa beforeAll para setup costoso

Debugging Tips

1. Logs Detallados

console.log('[DEBUG]', {
  userId: user?.profile.id,
  hackathonId: hackathonId,
  data: data,
});

2. Sentry Integration

Los errores se capturan automáticamente con Sentry:

import { captureError } from '@/core/errors';

try {
  // código
} catch (error) {
  captureError(error, {
    context: 'functionName',
    userId: user?.profile.id,
  });
}

3. Prisma Studio

Inspecciona la base de datos:

pnpm db:studio

4. Network Tab

Revisa requests en DevTools → Network:

• Server Actions
• API Routes
• WebSocket connections

5. React DevTools

Inspecciona estado de componentes:

• Props
• State
• Hooks

Recursos

• Next.js Debugging
• Prisma Troubleshooting
• Clerk Troubleshooting
• Supabase Troubleshooting

---

Siguiente: Testing Guide