Error al publicar Bolt en Netlify: cómo leer el log
Dónde ver el error real cuando tu proyecto de Bolt.new no se publica en Netlify, las causas más comunes y cómo corregir y comprobar cada una.
Read in English →
Cuando un proyecto de Bolt.new falla al publicarse en Netlify, la causa casi siempre está escrita en la salida del build, unas líneas antes del mensaje final de error. Busca el primer error real (un módulo que no existe, un error de TypeScript, una carpeta de salida equivocada, una versión de Node distinta), corrige solo eso y vuelve a publicar. La última línea, del tipo Build script returned non-zero exit code: 2, solo avisa que algo falló antes.
En esta guía verás dónde está ese registro en Bolt y en Netlify, cómo leerlo sin perderte, qué provoca la mayoría de los fallos y qué dejar configurado para que no se repita.
¿Dónde encuentro el log del build?
Primero identifica cómo publicas. Hay quien usa el botón Publish de Bolt después de elegir Netlify como proveedor en Domains & Hosting, y hay quien conecta el repositorio de GitHub a un sitio de Netlify para que Netlify compile cada commit. El registro vive en un lugar distinto en cada caso.
- En Bolt. Abre la vista de código (el icono
</>), despliega el panel inferior y entra a la pestaña Publish Output. Ahí queda la salida de cada publicación. La pestaña Bolt, al lado, muestra lo que pasa mientras corre la vista previa. - En Netlify. Abre el sitio en el panel de Netlify, ve a Deploys y haz clic en el despliegue fallido. El deploy log es el registro completo del build, con el error incluido. Si Netlify compila desde GitHub, este es el registro que importa.
Si Bolt directamente no logra publicar, la página de problemas de publicación de Bolt propone una salida manual: ejecutar npm run build en la terminal de Bolt, descargar el proyecto y subir la carpeta resultante con el despliegue de arrastrar y soltar de Netlify.
¿Cómo se lee un log que falló?
Empieza por el final, donde están el resumen y el código de salida, y sube hasta la primera línea que empiece con error, Error:, ERR! o Module not found. Copia esa línea y las cinco o diez que la rodean: eso es lo que le pegas a Bolt o le mandas a un desarrollador. Líneas como Command failed with exit code 1 solo repiten el veredicto.
¿Qué suele romper la publicación de Bolt en Netlify?
| Lo que dice el log | Causa probable | Solución |
|---|---|---|
Module not found: Can't resolve '...' | Un import apunta a un archivo o paquete que no existe, o cambia una mayúscula | Corregir la ruta o instalar el paquete |
Errores de TypeScript (TS2322, TS2345…) | El script de build revisa tipos antes de compilar | Corregir los tipos, de uno en uno |
Could not find a build output directory to publish. | Los archivos finales quedaron en otro lugar, o no se generaron | Alinear comando y carpeta de salida (dist en Vite) |
ERESOLVE o Conflicting peer dependency | Versiones de paquetes que no se llevan | Alinear versiones |
Errores de sintaxis o de engines | Netlify compila con otra versión de Node | Fijar la versión de Node |
| El build pasa pero la página sale en blanco | Faltan variables de entorno al compilar | Agregarlas donde corre el build y recompilar |
| Al recargar una ruta aparece un 404 | App de una sola página sin regla de respaldo | Redirigir todo a index.html |
Mayúsculas en los nombres de archivo
El sistema de archivos donde compila Netlify distingue mayúsculas, así que Header.tsx y header.tsx son archivos distintos. Si el log dice que no encuentra un módulo que sí ves en el proyecto, compara letra por letra el import con el nombre real.
La carpeta de salida
Los proyectos con Vite, la mayoría en Bolt, compilan en dist. Si el directorio de publicación apunta a build o a la raíz, el build pasa y el sitio queda vacío. En un archivo netlify.toml se ve así:
[build]
command = "npm run build"
publish = "dist"La versión de Node
La vista previa de Bolt corre en tu navegador; un build en Netlify usa la versión de Node fijada en tu sitio de Netlify. Si un paquete necesita un Node más nuevo, verás errores de sintaxis o de versión. La documentación de dependencias de Netlify permite fijarla con la variable NODE_VERSION o con un archivo .nvmrc o .node-version que diga, por ejemplo, 22. Usa la misma versión mayor con la que pruebas en tu computadora.
Conflictos de dependencias
Un ERESOLVE significa que dos paquetes piden versiones distintas de una dependencia compartida. Lo correcto es actualizar o bajar uno de los dos hasta que coincidan. Como parche temporal, Netlify documenta la variable NPM_FLAGS con el valor --legacy-peer-deps. Lo explicamos a fondo en errores de dependencias npm en Bolt.
Variables de entorno que faltan
Las variables que empiezan con VITE_ quedan grabadas dentro del JavaScript al compilar. Cuando el build lo hace Netlify, solo ve las variables configuradas en Netlify, no tu .env de Bolt (que además no debería estar en GitHub). El build pasa y la app publicada falla con mensajes como supabaseUrl is required. Agrégalas en Netlify y lanza un despliegue nuevo, porque cambiar una variable no recompila nada por sí solo. Qué puede ir ahí y qué no lo explicamos en variables de entorno en Bolt.
Rutas que dan 404 al recargar
Una app de React de una sola página tiene un único archivo real, index.html, y Netlify necesita una regla que mande todas las rutas ahí. Crea public/_redirects con:
/* /index.html 200¿Qué no puede alojar Netlify de un proyecto de Bolt?
La documentación de Bolt es clara: el hosting de Netlify desde Bolt sirve para sitios que corren completos en el navegador. No aloja una base de datos ni un backend tradicional. Si tu proyecto depende de Bolt Database, de funciones de servidor o del inicio de sesión de Bolt, conviene publicar en el hosting de Bolt, o mover el backend a un lugar propio (por ejemplo, un proyecto de Supabase a tu nombre) y dejar en Netlify solo el frontend.
Dos límites más:
- Bolt no publica proyectos que pasen de 100MB en total. Casi siempre son imágenes y videos; súbelos a un almacenamiento externo.
- Si duplicas un proyecto, pierde la conexión con Netlify y al reconectar se crea un sitio nuevo, así que tu dominio propio tiene que apuntar a ese sitio nuevo.
¿Cómo confirmo que quedó arreglado?
- Ejecuta
npm run builden la terminal de Bolt. Si falla ahí, también fallará en Netlify. - Publica y revisa que el deploy log termine en un despliegue publicado, sin errores arriba.
- Abre la URL en una ventana privada, recarga una página que no sea la de inicio y mira la consola del navegador.
- Prueba la función que depende de variables de entorno; casi siempre es el inicio de sesión.
¿Cómo evito que vuelva a pasar?
- Deja un
netlify.tomlen el proyecto con el comando, la carpeta y la versión de Node, para que la configuración viaje con el código. - Corre
npm run buildantes de cada publicación, no solo cuando algo se ve raro. - Conecta el proyecto a GitHub para que cada despliegue corresponda a un commit al que puedas volver.
- Anota qué variables necesita la app y dónde está configurada cada una.
Si todavía estás eligiendo dónde alojar, mira nuestra comparación Netlify o Vercel.
Respuestas rápidas
¿Por qué funciona en la vista previa de Bolt y falla en Netlify? Porque son entornos distintos: otra versión de Node, un sistema de archivos que distingue mayúsculas y un build de producción más estricto. El log te dice cuál de esas diferencias pesa.
¿Sirve darle a Publish varias veces? No. Sin cambios, el mismo build falla igual. Lee el primer error, corrígelo y publica.
¿Puedo publicar en Netlify sin conectar mi cuenta de Bolt? Sí. Compila en Bolt, descarga el proyecto y arrastra la carpeta de salida a la página de despliegue manual de Netlify.
¿Sigue fallando?
Si el log apunta a algo que no sabes seguir, empieza con la revisión gratuita de tu URL publicada. Para ir más a fondo, nuestro servicio para arreglar apps de Bolt parte de una revisión del código y un precio cerrado por cada arreglo antes de tocar nada, y los planes de mantenimiento mantienen los despliegues sanos después. También puedes mandarnos el log y una persona te responde en un día hábil.
