Errores de npm install: Cada error común y cómo solucionarlo

Ejecutar npm install y encontrarse con un muro de texto rojo es un rito de paso para todo desarrollador JavaScript. Ya sea un error de permisos en macOS, un conflicto de dependencias en un monorepo o una cache corrupta en CI, la solucion suele ser directa una vez que sabes que buscar. Esta guia cubre cada error comun de npm install, explica por que ocurre y te da los comandos exactos para solucionarlo.

Diccionario de errores: tabla de referencia rapida

EACCES: corregir errores de permisos

Este es el error mas comun en macOS y Linux. Ocurre cuando npm intenta instalar paquetes globales en un directorio del sistema como /usr/local/lib/node_modules.

Solucion en macOS / Linux (Recomendado: usar nvm)

La mejor solucion permanente es usar un gestor de versiones de Node para que npm instale en tu directorio de usuario:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then install Node
nvm install --lts
nvm use --lts

# Verify — npm now installs to ~/.nvm/
which npm
# /home/youruser/.nvm/versions/node/v20.x.x/bin/npm

Alternativa: cambiar manualmente el directorio por defecto de npm:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.bashrc or ~/.zshrc:
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bashrc

Opcion nuclear (no recomendada para la mayoria):

# NOT recommended — changes system directory ownership
sudo chown -R $(whoami) /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/bin
sudo chown -R $(whoami) /usr/local/share

Solucion en Windows

En Windows, ejecuta tu terminal como Administrador, o mejor aun, usa nvm-windows:

# Install nvm-windows from:
# https://github.com/coreybutler/nvm-windows/releases

# Then in an elevated (Admin) PowerShell:
nvm install lts
nvm use lts

# Or fix npm prefix for current user:
npm config set prefix %APPDATA%\npm

ERESOLVE: corregir conflictos de dependencias

Desde npm 7, los conflictos de peer dependencies causan que la instalacion falle por defecto. Veras un diagrama de arbol mostrando que paquetes estan en conflicto.

Salida de error tipica:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @some-org/some-package@2.1.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from some-library@3.5.0
npm ERR! node_modules/some-library
npm ERR!   some-library@"^3.5.0" from the root project

--legacy-peer-deps vs --force

--legacy-peer-deps le dice a npm que ignore completamente los conflictos de peer dependencies (mismo comportamiento que npm 6). --force fuerza la instalacion. Cuando usar cada uno:

# Option 1: Ignore peer deps (safest workaround)
npm install --legacy-peer-deps

# Option 2: Force install (overrides everything)
npm install --force

Enfoque preferido — fijar la dependencia en conflicto:

// In package.json — add "overrides" to pin the conflicting dep
{
  "overrides": {
    "some-library": {
      "react": "^18.2.0"
    }
  }
}

// Then run:
// npm install

Corrupcion de node_modules: cuando y como eliminar y reinstalar

A veces node_modules entra en un estado corrupto. Los sintomas incluyen errores "Cannot find module" para paquetes en package.json, o fallos de compilacion extranos despues de cambiar de rama.

Cuando eliminar node_modules

• Despues de cambiar a ramas con arboles de dependencias diferentes.
• Despues de resolver conflictos de fusion en package-lock.json.
• Cuando aparece "Module not found" para un paquete claramente instalado.
• Despues de actualizar Node.js a una nueva version principal.

Como hacer una reinstalacion limpia

Comando multiplataforma (bash):

rm -rf node_modules package-lock.json
npm install

Windows (PowerShell):

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Usando npx:

npx rimraf node_modules
npm install

Si los problemas persisten, tambien limpiar la cache de npm:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Conflictos de package-lock.json: estrategias de fusion

Cuando varios desarrolladores cambian dependencias, los conflictos de fusion de package-lock.json estan casi garantizados. Nunca intentes resolverlos manualmente — el archivo es generado automaticamente.

Estrategia de fusion recomendada

Aceptar cualquier lado del conflicto (no importa cual):

# Accept "theirs" (the incoming branch's version)
git checkout --theirs package-lock.json
git add package-lock.json

# OR accept "ours" (your branch's version)
git checkout --ours package-lock.json
git add package-lock.json

Regenerar el archivo de bloqueo:

npm install

Hacer commit del resultado:

git add package-lock.json
git commit -m "chore: regenerate package-lock.json after merge"

Prevenir conflictos con .gitattributes

Agrega esto a tu .gitattributes para resolver automaticamente conflictos del archivo de bloqueo:

# .gitattributes
package-lock.json merge=ours

Incompatibilidad de version de Node.js

Muchos paquetes requieren versiones especificas de Node.js. Si tu version es muy antigua (o muy nueva), npm install puede fallar con errores de compilacion.

Verificar la version requerida

Busca el campo engines en package.json:

// package.json
{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

// Check your current version:
// node -v
// npm -v

Usar nvm o fnm para cambiar versiones

nvm (Node Version Manager):

# List available versions
nvm ls-remote

# Install a specific version
nvm install 20

# Switch to a version
nvm use 20

# Set a default
nvm alias default 20

fnm (Fast Node Manager) — alternativa mas rapida:

# Install fnm (Rust-based, faster than nvm)
curl -fsSL https://fnm.vercel.app/install | bash

# Install and use a version
fnm install 20
fnm use 20
fnm default 20

Crea un archivo .nvmrc en la raiz del proyecto para que todo el equipo use la misma version:

# Create .nvmrc file
echo "20" > .nvmrc

# Team members just run:
nvm use
# or
fnm use

Problemas CI/CD: builds de Docker y GitHub Actions

npm install se comporta diferente en entornos CI. El cache, permisos y configuracion de red necesitan atencion especial.

Builds de Docker

Errores comunes en Dockerfiles:

# BAD Dockerfile — no layer caching, uses npm install
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

# GOOD Dockerfile — proper layer caching, uses npm ci
FROM node:20-alpine
WORKDIR /app

# Copy package files first (layer caching!)
COPY package.json package-lock.json ./

# Use npm ci for deterministic installs
RUN npm ci --ignore-scripts

# Then copy the rest of the source
COPY . .

# Run any build steps after copy
RUN npm run build

CMD ["node", "index.js"]

Puntos clave: copiar primero los archivos package para cache de capas, usar npm ci en lugar de npm install en CI (mas rapido y deterministico), usar --ignore-scripts si no se necesitan scripts postinstall.

Cache de GitHub Actions

Un cache adecuado puede reducir el tiempo de instalacion en mas del 70%:

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'  # Caches ~/.npm automatically

      - run: npm ci       # Deterministic install
      - run: npm test
      - run: npm run build

Diagrama de decision: npm install fallo — sigue esta guia

Usa este diagrama para diagnosticar tu fallo de npm install:

Preguntas frecuentes