Vercel: npm run build exited with 1, cómo arreglarlo

El mensaje “Error: Command “npm run build” exited with 1” en Vercel solo te dice que la construcción de tu app falló; no dice por qué. El error real está unas líneas más arriba en el log del build. Las causas más comunes son: un import con mayúsculas/minúsculas incorrectas, un error de TypeScript, una variable de entorno que no existe en Vercel o una versión distinta de Node.

Build es el proceso que convierte tu código en los archivos finales que se publican. Lo explicamos en qué hace npm run build.

Paso 1: encuentra el error real

1. En Vercel abre tu proyecto → Deployments.
2. Da clic en el deploy fallido (en rojo).
3. Abre Build Logs.
4. Busca hacia arriba desde “exited with 1” la primera línea con error, Error: o failed.

Copia ese bloque completo. Es lo que necesitas para arreglarlo (y lo que le pegarías a la IA).

Paso 2: reproduce el error en tu computadora

npm install
npm run build

Si falla igual, arréglalo localmente: es más rápido que hacer deploys de prueba. Si localmente funciona y en Vercel no, ve a las causas 1, 3 y 4.

Causas más comunes y cómo arreglarlas

1. Mayúsculas y minúsculas en imports

Module not found: Can't resolve './components/Header'

Tu archivo se llama header.tsx pero lo importas como Header. Windows y macOS no distinguen mayúsculas, pero Vercel compila en Linux, que sí. Vercel lo explica en su guía de “module not found”.

Arréglalo haciendo que el import coincida exactamente con el nombre del archivo. Si renombras solo mayúsculas, git puede no detectarlo; usa un nombre temporal:

git mv src/components/header.tsx src/components/temp.tsx
git mv src/components/temp.tsx src/components/Header.tsx
git commit -m "corrige mayúsculas de Header"

2. Errores de TypeScript

error TS2322: Type 'string' is not assignable to type 'number'.

En desarrollo (npm run dev) muchos errores de tipo no detienen la app, pero en el build sí. El log te dice archivo y línea. Corrige el tipo; no desactives la revisión de TypeScript para que pase.

3. Variables de entorno faltantes

Si tu código usa import.meta.env.VITE_SUPABASE_URL o process.env.NEXT_PUBLIC_... y la variable no existe en Vercel, el build puede fallar o la app quedar rota. Agrégalas en Settings → Environment Variables con el mismo nombre exacto, para el entorno correcto (Production, Preview), y vuelve a hacer deploy. Ver variables de entorno en Vite y React.

4. Versión de Node distinta

Si el log menciona sintaxis no soportada o un paquete que exige otra versión de Node, revisa la versión en Settings → Build and Deployment → Node.js Version (el nombre puede variar según la versión del panel) o defínela en tu package.json:

{
  "engines": {
    "node": "20.x"
  }
}

5. Advertencias tratadas como errores (Create React App)

Treating warnings as errors because process.env.CI = true.

Vercel documenta que en proyectos con Create React App las advertencias se vuelven errores en el build. Su guía oficial indica agregar una variable CI con valor false. Mejor aún: corrige las advertencias (variables sin usar, dependencias faltantes en useEffect).

6. Dependencias que no instalan

npm ERR! ERESOLVE unable to resolve dependency tree

Hay paquetes con versiones incompatibles. Revisa que tu package-lock.json esté en el repositorio y actualizado. Como parche temporal se usa npm install --legacy-peer-deps, pero lo correcto es alinear las versiones.

7. Directorio de salida o preset equivocado

Si el build termina pero Vercel no encuentra los archivos, revisa en Settings → Build and Deployment que el Framework Preset sea el correcto (Vite, Next.js) y que el Output Directory coincida (dist en Vite).

8. Archivo de bloqueo de otro gestor de paquetes

Vercel decide si instalar con npm, pnpm, yarn o bun según el archivo de bloqueo que encuentra en el repositorio (package-lock.json, pnpm-lock.yaml, yarn.lock o bun.lockb). Las herramientas de IA a veces dejan dos de estos archivos, por ejemplo Bolt o Lovable con bun.lockb y tú con package-lock.json. El resultado: Vercel instala versiones distintas a las que probaste.

Qué hacer: quédate con el gestor que usas en tu computadora, borra los otros archivos de bloqueo y haz commit.

9. El proyecto está en una subcarpeta

npm ERR! enoent Could not read package.json

Si tu repositorio tiene la app dentro de una carpeta (frontend/, web/), Vercel busca package.json en la raíz y no lo encuentra. Indica la carpeta en Settings → Build and Deployment → Root Directory.

10. Se acaba la memoria

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Pasa con proyectos grandes o con imágenes pesadas que se procesan en el build. Antes de buscar más memoria, revisa si estás importando archivos enormes (videos, imágenes sin comprimir, un JSON de varios MB) desde src/. Moverlos a public/ o comprimirlos suele bastar.

Cómo leer un log muy largo

Los logs de Vercel pueden tener cientos de líneas de advertencias que no importan. Para no perderte:

• Usa la búsqueda del navegador (Ctrl + F) con la palabra error y ve a la primera coincidencia.
• Ignora líneas con warn o deprecated: son avisos, no la causa.
• Fíjate en el archivo y la línea que menciona (src/pages/Home.tsx:42); ahí empieza el problema.
• Si el error menciona un paquete de node_modules, el problema suele ser de versiones, no de tu código.

npm run build not working: si falla también en tu computadora

• Borra dependencias y reinstala:

rm -rf node_modules
npm install
npm run build

• Lee el primer error, no el último. Los demás suelen ser consecuencia.
• Si lo generó una IA (Lovable, Bolt, Cursor), pégale el error completo y pide que explique la causa antes de cambiar código. Ver corregir código con IA.

Errores comunes

• Leer solo la última línea del log.
• Hacer diez deploys de prueba en vez de correr npm run build local.
• Subir node_modules al repositorio.
• Desactivar TypeScript o ESLint en el build para que “pase”.

Si el build pasa pero la página sale en blanco o con 404, revisa error 404 en Vercel. Y si llevas horas atorado con el deploy, en Black Engine revisamos el log contigo por WhatsApp y te decimos qué línea está fallando.