Falló el deploy: cómo leer errores de build

Un build fallido suele soltar un muro de texto: avisos, stack traces, notas de obsolescencia y una última línea que dice que el comando terminó con error. Casi todo es ruido. Una línea, muchas veces bastante más arriba del final, nombra el problema real.

Encontrar esa línea es una rutina corta, y los errores que revela en builds de Node.js y Python se repiten bastante. Cada uno tiene una corrección conocida. Si "build" y "deploy" todavía te parecen términos confusos, empieza por qué es un deploy.

¿Qué línea de un log de build importa?#

Lee el log desde arriba, no desde abajo. Las herramientas de build se detienen en el primer fallo, pero siguen imprimiendo: el gestor de paquetes avisa de que un script falló, luego de que la instalación falló y luego el código de salida. Esas últimas líneas describen la consecuencia, no la causa.

Sigue esta rutina:

1. Busca en el log error, ERR!, ERROR: o FATAL.
2. Quédate con la primera coincidencia que no sea un aviso.
3. Lee las 5 a 10 líneas de alrededor. Los gestores de paquetes imprimen ahí mismo los nombres y versiones en conflicto.
4. Copia el mensaje exacto en tu búsqueda. El texto literal encuentra respuestas más rápido que una paráfrasis.

Los avisos (npm warn deprecated ...) rara vez rompen un build. Trátalos como ruido hasta haber encontrado un error real.

¿Por qué npm imprime ERESOLVE?#

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-app@1.0.0
npm error Found: react@19.0.0
npm error node_modules/react
npm error   react@"19.0.0" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react@"^18.0.0" from some-library@2.1.0

Un paquete declara una peer dependency, que significa "el proyecto que me usa debe proporcionar este paquete en este rango de versiones". Tu proyecto proporciona otra versión, así que npm no puede armar un árbol coherente. Por defecto, npm resuelve algunos conflictos con la dependencia no peer más cercana e imprime un aviso. Con strict-peer-deps activado, o cuando el conflicto no tiene solución, se convierte en un fallo.

Correcciones, de la mejor a la peor:

• Actualiza some-library a una versión que soporte la tuya.
• Baja o fija la versión del paquete que controlas, si no puedes actualizar la biblioteca.
• Pasa --legacy-peer-deps. Según la documentación de npm, esta opción ignora por completo las peerDependencies, como hacían npm 3 a 6. El build pasa, pero la incompatibilidad sigue ahí.

Evita --force como solución. Según la documentación de npm, quita protecciones contra efectos secundarios indeseados, y npm desaconseja con firmeza usarlo si no tienes claro lo que quieres hacer.

Si creas el lockfile con --legacy-peer-deps, pasa la misma opción a npm ci, o es probable que la instalación falle.

¿Por qué npm ci falla cuando npm install funciona?#

npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: express@5.1.0 from lock file

npm ci es el comando de instalación para builds automatizados. Necesita un package-lock.json existente, y si el lockfile y el package.json no coinciden, termina con un error en lugar de actualizar el lockfile. Es a propósito: así, cada build instala exactamente las versiones que probaste.

La corrección es local. Ejecuta npm install, haz commit del package-lock.json modificado y vuelve a hacer el deploy.

¿Qué significa "Cannot find module" y por qué falla solo en el servidor?#

Dos herramientas distintas imprimen un texto parecido.

Error: Cannot find module 'express'

Este es Node.js cargando un módulo CommonJS. Con módulos ES (import), el mismo problema se lee Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from .... En ambos casos, el paquete no está instalado o está en devDependencies mientras el build hace una instalación solo de producción. Revisa primero el package.json y luego que la ruta del import coincida exactamente con el nombre del archivo, mayúsculas incluidas. Un archivo llamado Utils.js importado como ./utils funciona en Windows y macOS, pero falla en Linux.

src/index.ts(3,20): error TS2307: Cannot find module './utils' or its corresponding type declarations.

Este es el compilador de TypeScript. O el archivo no existe en esa ruta, o TypeScript no encuentra los tipos de un paquete. Instala el paquete @types/... correspondiente o revisa moduleResolution: la documentación de TypeScript dice que debe coincidir con el resolvedor de tu runtime o bundler. Recuerda que los alias de paths afectan la verificación de tipos, pero no el código emitido, así que el código puede compilar y aun así fallar al ejecutarse.

¿Por qué cambian las versiones entre tu computadora y el build?#

Las diferencias de versión causan muchos de estos fallos, porque tu computadora y el entorno de build rara vez ejecutan la misma versión. Una característica de sintaxis, un módulo nativo o una versión de un paquete puede existir en uno y no en el otro.

Declara la versión que probaste. En Node.js, añade un campo engines al package.json:

{
  "engines": {
    "node": ">=22"
  }
}

Por defecto, npm trata engines como algo orientativo y solo avisa, y solo cuando tu paquete se instala como dependencia. No detiene tu propio build a menos que engine-strict esté activado. En Python, indica la versión del intérprete en la documentación o las herramientas del proyecto y fija los paquetes en requirements.txt.

¿Qué significan los errores de build de pip?#

ERROR: Could not find a version that satisfies the requirement somepackage==9.9
ERROR: No matching distribution found for somepackage==9.9

La versión no existe, o ningún archivo de ella encaja con tu versión de Python y tu plataforma. Comprueba el nombre y la versión exactos en PyPI y que el paquete soporte tu versión de Python.

ERROR: Cannot install package_a==1.0 and package_b==2.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    package_a 1.0 depends on package_c<3.0,>=2.4
    package_b 2.0 depends on package_c==2.3

Este es el ResolutionImpossible de pip. Lee el bloque "conflict is caused by": dos paquetes necesitan rangos incompatibles de un tercero. Afloja tus propias versiones fijadas, quita los paquetes que no necesitas o actualiza uno de los dos.

error: command 'gcc' failed: No such file or directory
ERROR: Failed building wheel for somepackage

Algunos paquetes no publican un wheel precompilado para tu plataforma, así que pip los compila desde el código fuente, lo que necesita un compilador y cabeceras del sistema. Prefiere una versión que publique wheel. La opción --only-binary :all: hace que pip rechace compilar desde el código fuente, así que falla rápido si no existe wheel.

¿Y si el build se queda sin memoria?#

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

La parte central del mensaje cambia según la situación (por ejemplo, Ineffective mark-compacts near heap limit), pero termina en JavaScript heap out of memory.

O el build simplemente se detiene con el código de salida 137, que por convención del shell es 128 más la señal 9 (SIGKILL). Los bundlers, TypeScript en un proyecto grande y el procesamiento de imágenes pueden usar más memoria de la que permite un contenedor pequeño. Node.js documenta --max-old-space-size (en MiB) como el límite de la sección de memoria antigua de V8 y sugiere unos 1536 en una máquina con 2 GiB, para dejar espacio a otros usos:

NODE_OPTIONS=--max-old-space-size=1536 npm run build

Subir el límite solo ayuda si la máquina tiene de verdad esa memoria. Si no la tiene, el sistema mata el proceso, y ese es el 137. Entonces quedan dos salidas, más RAM para el build o menos trabajo por build: desactiva los source maps, divide el proyecto o compila localmente y sube el resultado.

¿Cómo evitar que el mismo fallo vuelva?#

• Compila igual que el servidor: borra node_modules y ejecuta npm ci, o crea un entorno virtual limpio y ejecuta pip install -r requirements.txt.
• Haz commit de los lockfiles y fija las versiones del runtime.
• Revisa la configuración pronto. Las variables de entorno que faltan fallan tarde y de forma confusa, así que lee qué son las variables de entorno.
• Ejecuta el build en CI antes del deploy, como en deploys automáticos con GitHub Actions.
• Conoce tu presupuesto de memoria. Cuánta RAM y CPU necesita tu app explica cómo estimarlo.

Cómo hacerlo en Square Cloud#

En Square Cloud la rutina de lectura es la misma, pero el error aparece en otro momento, porque no hay etapa de build. Al iniciar, la plataforma instala las dependencias (npm install cuando no existe node_modules, sin las devDependencies, o pip install -r requirements.txt en Python), y la salida de esa instalación aparece en los logs de la aplicación. Si tu proyecto necesita compilarse, ejecuta el build en un CI externo, como GitHub Actions, y envía el resultado, o pon el build en el comando de inicio.

Haces el deploy subiendo un ZIP, con la CLI, desde GitHub o con la extensión de VS Code. Los logs llegan en tiempo real al panel, a la CLI y a VS Code, así que puedes leer la primera línea de error en cuanto aparece.

La memoria la defines tú. Una aplicación puede usar hasta 32 GB del pool de RAM compartido del plan, y cambias la cantidad en la configuración de la aplicación o por la API, lo que ayuda si la aplicación se queda sin heap mientras se ejecuta. Las variables de entorno se definen por aplicación, y un cambio vale en el siguiente reinicio, sin rebuild. El agente Cubic del panel también puede leer tus logs para ayudar a diagnosticar fallos, siempre que tú se lo pidas.

Mira lo que admite cada runtime en la página de runtimes.