Why Does Your Build Work Locally but Fail on Deploy?

Why your build works locally but fails on deploy (and how to fix it)

Short answer:it's almost always a problem withenvironment parity: your machine and the build server aren't identical. The most common causes are environment variables that exist on your machine but not on the server, dependencies you have installed globally or asdevDependencies, diferencias de versión de Node/Python, archivos bloqueados por .gitignore, y la sensibilidad a mayúsculas de Linux (tu Mac o Windows perdona errores de mayúsculas en los imports; el servidor no). La solución pasa por reproducir el entorno de producción localmente y eliminar las suposiciones implícitas.

La causa raíz: "en mi máquina funciona"

El build que pasa en tu laptop y falla en el servidor es uno de los problemas más viejos y frecuentes del desarrollo. La razón de fondo es siempre la misma: tu entorno local y el de build no son iguales. Tu máquina acumula configuración, variables, dependencias globales y rutas que diste por sentadas, y el servidor arranca limpio.

Diagnosticar esto es un proceso de eliminar diferencias una por una. Estas son las que explican la gran mayoría de los casos.

1. Variables de entorno que existen solo en tu máquina

Tienes una variable en tu .env local o exportada en tu shell, y el código la usa durante el build. En el servidor no está definida, y el build falla o produce un artefacto roto.

Cómo diagnosticarlo: busca en tu código toda lectura de process.env. (Node) u os.environ (Python) que ocurra en tiempo de build.

Cómo solucionarlo: declara explícitamente cada variable en la configuración del entorno de deploy. Nunca subas el .env al repositorio; en su lugar documenta las variables requeridas en un .env.example versionado.

# .env.example (este SÍ se versiona; el .env real no)
DATABASE_URL=
API_KEY=
NODE_ENV=production

2. NODE_ENV=production cambia el comportamiento

Muchas apps de Node ejecutan lógica distinta según NODE_ENV. Un bug puede aparecer solo cuando ese valor es production —por ejemplo, al construir assets o comprimir imágenes— y nunca verse en desarrollo.

Cómo solucionarlo: reproduce el bug localmente forzando el mismo valor antes de buildear.

NODE_ENV=production npm run build

Si falla igual que en el servidor, ya tienes el caso aislado en tu máquina.

3. La dependencia está en devDependencies, no en dependencies

Tu build necesita un paquete (un bundler, un compilador de TypeScript, etc.), pero está listado en devDependencies. Many platforms installonly dependenciesin production, so the package never arrives and the build fails with "command not found" or "module not found".

Cómo solucionarlo:moves todependencieseverything neededduring the build. Leave indevDependenciesonly what you use to develop and test locally.

npm install --save typescript # pasa de dev a dependency

4. Sensibilidad a mayúsculas: Linux no perdona

Este es el clásico silencioso. macOS y Windows usan sistemas de archivos que ignoran mayúsculas/minúsculas, así que import Button from './components/button' funciona aunque el archivo se llame Button.tsx. El servidor de build corre Linux, que sí distingue mayúsculas, y ese mismo import falla con "module not found".

Cómo diagnosticarlo: revisa que cada ruta de import coincida exactamente —carácter por carácter— con el nombre real del archivo y la carpeta.

Cómo solucionarlo: corrige los imports para que coincidan con el nombre exacto del archivo. Para prevenirlo a futuro, activa la verificación de mayúsculas en tu bundler o linter.

5. Versión de Node, Python o del runtime distinta

Tú corres una versión local; el servidor usa otra por defecto. Una API que existe en tu versión puede no existir en la del build, o al revés.

Cómo solucionarlo: fija la versión explícitamente en el proyecto para que el servidor use la misma.

// package.json
{
"engines": {
"node": "22.x"
}
}

# .python-version o runtime.txt según la plataforma
3.12

Verifica tu versión local con node --version o python --version y haz que coincidan.

6. Un archivo necesario está bloqueado por .gitignore

El archivo existe en tu disco pero una regla demasiado amplia del .gitignore impide que entre al repositorio. Como el build parte del repo, el archivo simplemente no está.

Ejemplo clásico: una regla lib ignora recursivamente cualquier carpeta llamada lib, incluyendo una que tu app necesita dentro de node_modules de un paquete propio o en tu código.

Cómo solucionarlo: ancla la regla a la raíz con una barra inicial para que solo aplique a la carpeta del nivel superior.

# Antes: ignora todas las carpetas "lib" en cualquier nivel
lib

# Después: ignora solo /lib en la raíz del proyecto
/lib

Confirma qué se está versionando realmente con git ls-files | grep <archivo>.

7. Lockfile desactualizado o sin commitear

Si tu package-lock.json, yarn.lock o poetry.lock no está commiteado o está desincronizado con el package.json, el servidor puede resolver versiones distintas a las tuyas y romper el build.

Cómo solucionarlo: versiona siempre el lockfile e instala con el comando que respeta el lock exacto.

npm ci # instala exactamente lo del lockfile (no lo modifica)
# en lugar de:
npm install # puede actualizar versiones

8. Dependencias nativas o herramientas de compilación ausentes

Algunos paquetes compilan código nativo (C/C++) durante la instalación y requieren herramientas de build (gcc, make, python) que tu máquina tiene pero la imagen del servidor no.

Cómo solucionarlo: revisa los logs del build para identificar el paquete que falla y asegúrate de que la imagen base incluya las herramientas de compilación necesarias, o usa una versión precompilada del paquete cuando exista.

9. El build se queda sin memoria

En local tienes 16 o 32 GB de RAM; el servidor de build puede tener mucho menos. Builds grandes (especialmente de frontend) mueren con un error de memoria que jamás verías localmente.

Cómo diagnosticarlo: busca en los logs mensajes como "JavaScript heap out of memory" o que el proceso muera sin razón aparente (señal de OOM).

Cómo solucionarlo: reduce el consumo del build (divide bundles, limita la concurrencia) o sube el límite de memoria del proceso si la plataforma lo permite.

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

10. Variables necesarias en build-time que no llegan al build

Distinto del punto 1: algunas plataformas inyectan las variables solo en runtime (cuando la app corre), no durante el build. Si tu compilación necesita una variable —por ejemplo, una URL pública de API para frontend— y solo está disponible en runtime, el build usará un valor vacío.

Cómo solucionarlo: confirma en la documentación de tu plataforma qué variables están disponibles en build-time y declara explícitamente las que necesite el proceso de compilación en esa fase.

Checklist de diagnóstico rápido

Cuando un build pase en local y falle en el deploy, recórrelo en este orden:

1. ¿Reproduces el fallo con NODE_ENV=production npm run build en local?
2. ¿Todas las variables de entorno del build están declaradas en el servidor?
3. ¿Las dependencias del build están en dependencies, no en devDependencies?
4. ¿Los imports coinciden exactamente en mayúsculas con los nombres de archivo?
5. ¿La versión de Node/Python está fijada y coincide con la local?
6. ¿Hay archivos necesarios bloqueados por .gitignore?
7. ¿El lockfile está commiteado y usas npm ci?
8. ¿Los logs mencionan memoria, herramientas de compilación o un paquete nativo?

El 95% de los casos se resuelve en uno de estos ocho puntos.

Preguntas frecuentes

¿Por qué mi import funciona en Mac pero falla en el servidor? Porque macOS y Windows ignoran mayúsculas en los nombres de archivo, pero Linux —que corre en el servidor— sí las distingue. Un import como ./Button no encontrará un archivo llamado button.tsx. Corrige la ruta para que coincida exactamente.

¿Cuál es la diferencia entre npm install y npm ci en un deploy? npm install puede actualizar versiones y modificar el lockfile; npm ci instala exactamente lo que dice el lockfile y falla si está desincronizado. Para builds reproducibles en deploy, usa siempre npm ci.

¿Por qué el build se queda sin memoria solo en el servidor? Tu máquina local suele tener mucha más RAM que el entorno de build. Builds grandes superan el límite del servidor y mueren con "heap out of memory". Reduce el tamaño del build o ajusta el límite de memoria del proceso.

¿Debo subir mi archivo .env al repositorio para que el deploy funcione? No. Nunca versiones el .envreal. Declare the variables in your deploy platform's configuration and version only a.env.examplewithout values as documentation.

Quick checklist before investigating a failed build

When a build fails only on the server, the temptation is to review the code. But in most cases the code is fine: the problem lies in what the code assumes about the environment. This list covers the checks that resolve over 80% of these incidents without needing to debug application logic.

Go through each point in order. If you reach the end without finding the cause, you most likely have an implicit global dependency or a different build script than the one you use locally.

1. 1Compare environment variablesCross-reference your local .env with the variables configured in the CI/deploy platform. Pay special attention to those read at build time, not just at runtime.
2. 2Verify the lock fileEnsure that package-lock.json, yarn.lock, or equivalent is versioned and not in .gitignore. Without it, exact dependency versions are not deterministic.
3. 3Revisa la capitalización de importsSi el servidor usa Linux y tu máquina macOS o Windows, cualquier diferencia de mayúsculas en rutas de import causará fallo. Usa un linter que detecte esto automáticamente.
4. 4Confirma que devDependencies no se usan en buildSi tu bundler o compilador vive en devDependencies y el servidor hace npm install sin --include=dev, la herramienta no existirá en el entorno de build.
5. 5Fija la versión de runtimeEspecifica la versión exacta de Node o Python en tu configuración de CI (por ejemplo, con .nvmrc o engines en package.json) y usa la misma localmente.

Close the gap between local and production

Every time a build fails only on the server, you're paying the cost of an undocumented assumption: a variable that only existed in your shell, a global dependency you installed months ago and forgot about, or an import that your file system let slide. Environment parity isn't a luxury, it's the baseline for predictable deploys.

The goal isn't for your server to look like your machine, but for both to behave identically based on the same explicit definition: pinned versions, declared variables, unambiguous files.

1. 1Delete node_modules and run the buildIf it fails, you have implicit or global dependencies that aren't declared.
2. 2Unset all variables in your shellOpen a clean terminal and run only what your CI runs. Whatever is missing is what's missing on the server.
3. 3Pin the exact runtime versionUse .nvmrc, engines in package.json, or a Dockerfile that specifies the base image.