MOTOKO BASEDocumentación
Solución de problemas
Problemas frecuentes de Motoko Base y correcciones — auth, OAuth, base de datos, email, billing, storage, Sentry y fallos de build.
Correcciones rápidas para problemas que suelen aparecer en la primera configuración o en el deploy a producción. Para detalles de env, consulta Environment Variables.
La autenticación no funciona
Síntomas: No se puede iniciar sesión, la sesión se pierde al refrescar, bucles de redirección, cookies no establecidas.
| Comprobación | Corrección |
|---|---|
Falta BETTER_AUTH_SECRET | Defínelo en .env — obligatorio en producción |
BETTER_AUTH_URL incorrecto | Debe coincidir con la URL que abres en el navegador (incluido http:// vs https://, puerto, sin problemas de barra final) |
Desajuste con NEXT_PUBLIC_APP_URL | Alinea ambos al mismo origen en cada entorno |
| Base de datos caída / migraciones no aplicadas | Verifica DATABASE_URL, ejecuta pnpm db:migrate |
| Email no verificado | El dashboard requiere verificación — revisa el buzón o usa /verify-email |
Consulta Better Auth e Installation.
Error de callback de OAuth
Síntomas: redirect_uri_mismatch, error de Google/GitHub tras autorizar, botones sociales deshabilitados.
| Comprobación | Corrección |
|---|---|
| Botón deshabilitado | Define ambos GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET (o el par de GitHub); reinicia el servidor de desarrollo |
| Desajuste de URL de callback | La consola del proveedor debe tener exactamente {BETTER_AUTH_URL}/api/auth/callback/google o .../github |
| Producción vs local | Añade URLs de callback separadas para localhost y el dominio de producción |
| Modo de pruebas de Google | Añade tu cuenta como usuario de prueba en la pantalla de consentimiento OAuth |
Consulta OAuth Setup.
Fallo de conexión a la base de datos
Síntomas: La app falla al arrancar, migraciones fallan, ECONNREFUSED, errores de timeout.
| Comprobación | Corrección |
|---|---|
DATABASE_URL sin definir o incorrecto | Cópialo del dashboard de Supabase/host; nunca uses NEXT_PUBLIC_* |
| Migraciones no aplicadas | pnpm db:migrate |
| Pooler vs directo | Runtime: transaction pooler (a menudo puerto 6543). Migraciones: prueba URL directa (puerto 5432) si falla el DDL |
| Proyecto de Supabase pausado | Restaura el proyecto en el dashboard de Supabase |
prepare: false | Ya está definido en src/lib/db/index.ts — obligatorio para el pooler de Supabase; no habilites prepared statements |
Consulta Database y Migrations.
No se envían los emails
Síntomas: No llega el email de verificación tras el registro, forgot-password no hace nada, falta el email de bienvenida.
| Comprobación | Corrección |
|---|---|
| Resend no configurado | Define RESEND_API_KEY y EMAIL_FROM |
| Remitente incorrecto | Usa un dominio verificado en producción; para pruebas prueba onboarding@resend.dev |
BETTER_AUTH_URL incorrecto | Los enlaces de reset/verificación apuntan al host equivocado — corrige el origen |
| Error en la página de forgot-password | La página comprueba isEmailConfigured() — se requieren ambas variables de Resend |
| Dashboard de Resend | Revisa los logs de Resend por rebotes o errores de API |
Consulta Email (Resend).
El checkout de Polar no se abre
Síntomas: La página de billing muestra “not configured”, el botón de checkout falla, permanece en Free tras el pago.
| Comprobación | Corrección |
|---|---|
| Faltan variables de entorno | POLAR_ACCESS_TOKEN, POLAR_PRO_MONTHLY_PRODUCT_ID, POLAR_WEBHOOK_SECRET |
| Sandbox vs production | POLAR_SERVER=sandbox con token/producto de sandbox — o production con credenciales en vivo |
| URL del webhook | {APP_URL}/api/billing/webhooks/polar — debe ser accesible desde Polar |
| Tras el checkout | La página de billing usa getFreshBillingSummary en el redirect de éxito; confirma que el webhook se entregó |
| Sin cliente de Polar | El usuario necesita un cliente de Polar (creado al registrarse cuando billing está configurado) antes del portal |
Consulta Payments (Polar).
Fallo de subida a R2
Síntomas: La página de storage muestra mensaje de configuración, error de URL prefirmada, fallo CORS en la subida del navegador, 403 en PUT.
| Comprobación | Corrección |
|---|---|
Faltan variables R2_* | Define account ID, access key, secret y nombre del bucket |
| Nombre de bucket con barra | my-bucket/demo → bucket my-bucket, prefix demo/ — o usa R2_PREFIX |
| CORS | Añade el origen de tu app a la política CORS del bucket R2 en Cloudflare |
| Archivo demasiado grande / MIME incorrecto | Límites en src/features/storage/config.ts |
| Fallo de validación HEAD | El servidor valida la subida tras el PUT — comprueba que el objeto exista en el dashboard de R2 |
Consulta Storage (R2).
Sentry no recibe errores
Síntomas: No hay issues en el dashboard de Sentry tras lanzar un error de prueba.
| Comprobación | Corrección |
|---|---|
Probando en next dev | Sentry está desactivado en desarrollo — usa pnpm build && pnpm start o prueba en producción desplegada |
| DSN sin definir | Define NEXT_PUBLIC_SENTRY_DSN |
| Proyecto incorrecto | Confirma que el DSN coincide con el proyecto de Sentry que estás viendo |
| Bloqueadores de anuncios | El navegador puede bloquear Sentry — prueba la ruta /sentry-tunnel o un error del lado del servidor |
| Source maps | Define SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT en tiempo de build para stacks legibles |
Consulta Monitoring (Sentry).
Fallo de build
Síntomas: pnpm build termina con errores en local o en CI.
| Comprobación | Corrección |
|---|---|
| Versión de Node | Requiere Node ≥ 22 — ejecuta node -v |
| Errores de tipo | pnpm typecheck — corrige los problemas de TypeScript reportados |
| Errores de lint | pnpm lint |
| Env faltante en build | La mayoría de variables son solo de runtime; las de subida de Sentry solo hacen falta si usas source maps |
| MDX / docs | Ejecuta pnpm install para que postinstall (fumadocs-mdx) termine |
| Lockfile | Usa pnpm install — no mezcles npm/yarn |
pnpm lint && pnpm typecheck && pnpm test && pnpm build¿Sigues atascado?
- Vuelve a leer Installation y Configuración de producción
- Compara tu
.envcon.env.example - Revisa los dashboards de integraciones (Resend, Polar, Cloudflare, PostHog, Sentry)
- Busca en el README del repo y en los README de features bajo
src/lib/email/,src/lib/security/, etc.
Scripts — Referencia de comandos.
Referencia de configuración — Índice de archivos de configuración.