Error de build en Vercel: cómo leer el log y arreglarlo
Dónde está el error real en el log de un build fallido en Vercel, las causas más comunes en apps hechas con IA, cómo resolver cada una y cómo evitar que vuelva.
Read in English →
Cuando un despliegue en Vercel falla en el build, el mensaje que sirve casi nunca es la última línea roja. Esa línea solo dice que el comando de build terminó con código 1; la causa real aparece unas líneas más arriba y, en la gran mayoría de los casos, puedes reproducirla corriendo el mismo comando en tu computadora.
En esta guía verás dónde está el log, cómo leerlo de abajo hacia arriba, cuáles son las causas más frecuentes en apps generadas con Lovable, Bolt, v0 o Cursor y cómo comprobar el arreglo antes de volver a subir cambios.
¿Dónde encuentro el log del build?
- Abre tu proyecto en el panel de Vercel y entra a Deployments.
- Haz clic en el despliegue que tiene el estado de error.
- En Deployment Details, despliega el paso Building. Ahí está toda la salida de consola de la instalación y del build.
La guía oficial de Vercel para errores de build advierte sobre la trampa: el mensaje final (su ejemplo es yarn run build exited with 1) solo indica que el comando falló. Sube desde ahí hasta la primera línea que mencione un archivo, un paquete o una variable. Esa es la pista.
¿Y si no aparece ningún log?
A veces el despliegue falla antes de empezar el build y Vercel muestra el error en una ventana, sin el paso Building. Entre las razones documentadas están un vercel.json inválido, un Ignored Build Step que se saltó el build, un commit de alguien que no es miembro del equipo o una integración del Marketplace que no se pudo preparar. Ahí no sirve tocar el código: hay que resolver esa condición previa y volver a desplegar.
¿Cuáles son las causas más comunes?
Ubica el primer error con sentido y compáralo con esta tabla.
| Lo que dice el log | Causa habitual | Dónde se arregla |
|---|---|---|
Module not found o Cannot find module './components/Header' | Mayúsculas distintas entre el archivo y el import, o un archivo que nunca se subió | Renombrar el archivo o corregir el import y hacer commit |
| Un error de TypeScript con archivo y número de línea | Errores de tipos que la vista previa ignoraba y next build no | En el archivo y la línea que indica el log |
Una URL o clave undefined mientras se generan páginas | Falta una variable de entorno en ese entorno | Settings del proyecto, Environment Variables |
Mensajes sobre la versión de Node.js o el campo engines | El código pide otra versión de Node que la configurada | Settings, Build and Deployment, Node.js Version |
| Conflictos de dependencias o de lockfile al instalar | Dos lockfiles de gestores distintos, o paquetes incompatibles | Dejar un solo lockfile y alinear versiones |
| El build se canceló por memoria o tiempo | Superó los 8 GB de memoria del contenedor o el límite de 45 minutos | Reducir lo que hace el build |
Mayúsculas: en mi compu funciona, en Vercel no
macOS y Windows suelen tratar Header.tsx y header.tsx como el mismo archivo. Las máquinas Linux que compilan tu app, no. Las herramientas de IA a veces renombran un componente en un lugar y no en el import, y la vista previa sigue funcionando porque corre en un sistema más permisivo. Busca el import que aparece en el error, compara letra por letra y corrige el lado que esté mal. Si Git conserva el nombre viejo, renombra con git mv para que el cambio quede registrado.
Errores de tipos que la vista previa nunca mostró
Next.js revisa los tipos como parte de next build, así que un código que "andaba bien" en la vista previa del builder puede fallar aquí. No apagues la revisión de tipos para ver todo en verde. Abre el archivo y la línea del log: casi siempre es un valor que puede ser null, una prop que cambió de nombre o una función llamada con argumentos viejos después de una edición de la IA.
Variables de entorno que faltan durante el build
Si una página se genera durante el build y consulta Supabase, Stripe u otra API, el build también necesita esas variables. Cuando falta NEXT_PUBLIC_SUPABASE_URL, lo normal es un error que dice que la URL de Supabase es obligatoria o inválida, mientras el build recopila datos de las páginas. Revisa que la variable exista para el entorno que estás desplegando (Production y Preview son listas separadas) y recuerda que los cambios solo aplican a despliegues nuevos. Lo explicamos a fondo en la guía de variables de entorno en producción, preview y local.
Advertencias tratadas como errores
Algunas herramientas antiguas, sobre todo Create React App, hacen fallar el build por simples advertencias cuando existe la variable CI. Vercel avisa que activar el acceso a las variables de sistema puede convertir esas advertencias en errores. Lo correcto es resolver las advertencias que lista el log (variables sin usar, dependencias de hooks), no esconderlas.
¿Cómo reproduzco el fallo en mi computadora?
Vercel recomienda compilar localmente antes de desplegar, y es la forma más rápida de ir probando.
- Baja el código más reciente de GitHub, incluido lo último que subió la herramienta de IA.
- Instala dependencias con el mismo gestor que usa el proyecto (
npm cisi hay unpackage-lock.json). - Crea un archivo de entorno local con los mismos nombres de variables. Si usas la CLI de Vercel,
vercel env pulldescarga las variables de Development del proyecto. - Corre
npm run build(o el comando de build que aparece en la configuración del proyecto). - Arregla el primer error, vuelve a compilar y repite hasta que pase.
Si compila en tu máquina pero sigue fallando en Vercel, compara tres cosas: la versión de Node.js, las variables de entorno y que todos los archivos modificados estén realmente en el commit.
¿Conviene volver a desplegar sin la caché?
Pocas veces, pero ayuda cuando cambió una dependencia y la caché sigue restaurando algo roto. En la lista de despliegues elige Redeploy y deja sin marcar Use existing Build Cache, o usa vercel --force desde la CLI. Los builds fallidos no sobrescriben la caché, así que rara vez es la culpable. Pruébalo una vez, no como costumbre.
¿Cómo confirmo que quedó arreglado?
- El nuevo despliegue aparece como listo y el paso Building termina sin líneas rojas.
- Abre la URL y recorre las páginas que se generan en el build, el inicio de sesión y cualquier pantalla que lea datos.
- Si el problema era una variable, confirma que el valor es el de producción (mira una petición en la pestaña Network o un dato visible), no uno de prueba.
¿Cómo evito que el build se vuelva a romper?
- Compila antes de subir. Si trabajas en Cursor o en local, corre el build antes de cada push a la rama de producción.
- Usa despliegues de preview. Sube primero a una rama; Vercel arma un preview y solo fusionas si pasa. Te lo explicamos en la guía de un entorno de pruebas sencillo.
- Pide cambios chicos a la IA. Los prompts de "reorganiza todo" son los que dejan archivos renombrados e imports rotos.
- Fija la versión de Node en la configuración del proyecto o en
enginespara que no cambie sin aviso.
Respuestas rápidas
¿Por qué solo dice "exited with 1"? Esa línea solo informa que el comando falló. La causa está impresa más arriba: busca el primer error que nombre un archivo o un paquete.
¿Puedo desactivar la revisión de TypeScript? Puedes, pero estarías publicando el error en lugar de arreglarlo. En código escrito por IA, los errores de tipos suelen señalar datos que faltan de verdad.
Ayer compilaba y hoy no, sin cambios en el código. ¿Qué pasó? Revisa si cambió una variable de entorno, si se instaló una versión nueva de alguna dependencia o si se modificó la versión de Node.js del proyecto.
¿Te ayudamos con un build que no pasa?
Si el log apunta a algo que no logras seguir, nuestro servicio de mantenimiento de software cubre justo este tipo de arreglo. También puedes pasar tu URL por el chequeo gratuito o leer cómo rescatamos apps hechas con IA. Si el build se rompe una y otra vez porque el código de fondo está enredado, eso ya es desarrollo de software a medida y no un arreglo rápido, y te diremos cuál de los dos es.
