Errores comunes

Errores al instalar dependencias (yarn install)

Los más comunes al arrancar. Primero verifica tus versiones:

node --version  # Debe ser 20.x o 22.x (par/LTS)
yarn --version  # Debe ser 1.22.x

The engine "node" is incompatible / versión de Node incorrecta

Causa: tienes una versión de Node impar o muy vieja (ej. 19, 21, 23).

Fix: instala una versión par LTS (20 o 22). Con nvm: nvm install 22 && nvm use 22. Con Homebrew (Mac): brew install node@22. Luego yarn install de nuevo. Ver Prepara tu compu.

yarn: command not found / no se reconoce yarn

Causa: yarn no está instalado o la terminal no lo ve.

Fix: npm install -g yarn. En Windows, cierra y reabre la terminal después. Verifica con yarn --version.

EACCES: permission denied al instalar yarn

Síntoma: falla npm install -g yarn por permisos.

Fix (Mac): usa sudo npm install -g yarn (o, mejor, Homebrew: brew install yarn). Al usar sudo te pide la contraseña de tu Mac: no se ve nada mientras la escribes, es normal — escríbela y Enter. Windows: abre la terminal como Administrador y reintenta.

Windows: running scripts is disabled / no se puede cargar yarn.ps1

Síntoma: en PowerShell, al correr yarn (o npm) dice que la ejecución de scripts está deshabilitada.

Fix: corre una vez esto en PowerShell y responde S/Y:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Cierra y reabre la terminal, y reintenta.

Se queda pegado o falla por red / ETIMEDOUT / ENOTFOUND

Causa: conexión intermitente al registro de paquetes.

Fix: revisa tu internet y reintenta yarn install. Si sigue, limpia caché: yarn cache clean y reintenta.

Paquetes corruptos / lockfile inconsistente

Síntoma: errores raros de módulos tras un install a medias. (El lockfile — yarn.lock — es la lista exacta de versiones que usa el proyecto; si queda a medias, se confunde.)

Fix (reinstalación limpia) — borra la carpeta de paquetes y reinstala.

En Mac:

rm -rf node_modules
yarn install

En Windows (PowerShell):

Remove-Item -Recurse -Force node_modules
yarn install

Landing carga pero /docs da 404

Síntoma: navegas a localhost:3000/docs y ves 404.

Causa: la carpeta docs-content/ no existe o está vacía.

Fix: confirma que docs-content/ existe en la raíz del monorepo con archivos .mdx.

OPENAI_API_KEY is not defined

Síntoma: error al hacer una llamada de IA.

Fix: copia tu key de OpenAI a web/.env.local. Reinicia yarn dev (las env vars no se hot-reloadean).

Build de Vercel falla con Module not found

Síntoma: deploy falla con Cannot find module '@/...'.

Causa: olvidaste poner Root Directory: web en Vercel.

Fix: Vercel → Project → Settings → General → Root Directory = web. Re-deploy.

Supabase devuelve JWT expired

Síntoma: peticiones del cliente fallan con 401 después de un rato. (JWT expired significa que tu sesión de login caducó y no se renovó sola.)

Causa: el middleware (un archivo que se ejecuta antes de cada página y, entre otras cosas, renueva tu sesión) no está refrescando la sesión.

Fix: revisa que web/middleware.js exista y esté completo. Si no sabes cómo, pega el error en Cursor y pide que revise ese archivo.

El waitlist no guarda emails

Síntoma: el formulario responde "¡listo!" pero los emails no aparecen en Supabase.

Causa: es lo esperado por ahora — el formulario hoy responde pero aún no guarda en la base de datos. El guardado llega en la Semana 2, cuando conectes la base de datos.

Fix: nada que arreglar todavía. Si ya estás en Semana 2+ y sigue sin guardar, revisa que hayas subido el schema a Supabase y pega el problema en Cursor.