DEV Community

Cover image for 🧩 Cómo solucionar problemas de integridad en dependencias de Node.js
Sanders Gutérrez
Sanders Gutérrez

Posted on • Originally published at dev.to

🧩 Cómo solucionar problemas de integridad en dependencias de Node.js

#node #npm #backend #javascript

💡 Introducción: el día que NPM decide no cooperar

Estás instalando tus dependencias como siempre. Escribes npm install, presionas Enter, esperas unos segundos (o una eternidad 😴)... y de pronto, aparece el mensaje:

npm ERR! code EINTEGRITY
npm ERR! sha512-abc123... integrity checksum failed
Enter fullscreen mode Exit fullscreen mode

Respiras hondo... Vuelves a intentarlo... Nada... El mismo error... 😤😡🤬

Este tipo de problema ---tan frustrante como misterioso--- ocurre cuando el hash de integridad de un paquete descargado no coincide con el esperado. En otras palabras: NPM detecta que el archivo no es exactamente el mismo que debería ser según el registro oficial.

Aunque muchas guías recomiendan borrar node_modules o limpiar la
caché, existe un método no sé si más rápido, no sé si más limpio, pero definitivamente más preciso:
corregir el hash de integridad manualmente en el package-lock.json.

En este artículo, aprenderás a hacerlo paso a paso, con ejemplos reales y también te lo explico en video aquí "Cómo solucionar problemas de integridad en dependencias de Node.js".

🔍 Paso 1: Identificar la dependencia que está fallando

El primer paso es leer con atención el mensaje de error.
NPM te dirá qué dependencia está causando el problema. Por ejemplo:

npm ERR! EINTEGRITY: sha512 checksum failed for follow-redirects
Enter fullscreen mode Exit fullscreen mode

Esto significa que el paquete follow-redirects descargado no coincide con el que el lockfile esperaba.

También suele aparecer una línea que indica dónde encontrar el registro completo del error:

See the log for details: /ruta/al/npm-debug.log
Enter fullscreen mode Exit fullscreen mode

Ese archivo (npm-debug.log) contiene el detalle completo, pero en
general con el nombre del paquete basta para actuar.

🧭 Paso 2: Localizar el paquete en el package-lock.json

Una vez identificado el nombre, abrimos el archivo package-lock.json.

Este archivo guarda información exacta sobre las versiones y hashes de integridad de cada dependencia.

Busca el nombre del paquete, por ejemplo:

"follow-redirects": {
  "version": "1.15.0",
  "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.0.tgz",
  "integrity": "sha512-XYZ123..."
}
Enter fullscreen mode Exit fullscreen mode

El campo "integrity" es el que NPM compara al instalar.

Si ese valor no coincide con el que el registro oficial tiene, el
proceso falla.

⚙️ Paso 3: Obtener el hash de integridad correcto

Ahora que sabemos cuál es el paquete problemático, debemos obtener el hash correcto directamente desde el registro oficial de NPM.

Ejecuta:

npm show follow-redirects
Enter fullscreen mode Exit fullscreen mode

El comando mostrará información como esta:

dist:
  integrity: sha512-AbCdEfGh...
Enter fullscreen mode Exit fullscreen mode

El valor que ves ahí es el hash oficial, calculado a partir del
paquete original en el registro.

Esa es la cadena que debe reemplazar al valor incorrecto del
package-lock.json.

✏️ Paso 4: Actualizar el hash manualmente

Con el hash correcto copiado, regresa al package-lock.json y reemplaza el valor anterior por el nuevo.

En algunos proyectos, la misma dependencia puede aparecer varias veces (por ejemplo, como dependencia de otro paquete).

Por eso, te recomiendo buscar todas las apariciones del nombre del paquete y reemplazar el campo "integrity" en cada una.

Ejemplo de corrección:

"node_modules/follow-redirects": {
  "version": "1.15.0",
  "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.0.tgz",
  "integrity": "sha512-AbCdEfGh..."  ← nuevo hash
}
Enter fullscreen mode Exit fullscreen mode

Guarda el archivo.
No es necesario borrar node_modules todavía.

🔁 Paso 5: Reinstalar dependencias

Con el package-lock.json corregido, ejecuta nuevamente:

npm install
Enter fullscreen mode Exit fullscreen mode

NPM descargará los paquetes y verificará los hashes actualizados.
Si todo fue reemplazado correctamente, el error de integridad
desaparecerá para esa dependencia.

💬 En el video te muestro claramente cómo, tras corregir el hash de follow-redirects, el error deja de aparecer.

🧩 Paso 6: Aplicar el mismo método a otras dependencias

En algunos casos, el error se repite con otros paquetes.
Por ejemplo, la librería semver (una dependencia muy usada para el control de versiones).

El procedimiento es el mismo:

npm show semver
Enter fullscreen mode Exit fullscreen mode

Copia el valor de dist.integrity, busca todas las apariciones de
semver en el package-lock.json y reemplázalo.
Luego vuelve a ejecutar npm install.

Si la dependencia es indirecta (es decir, pertenece a otra librería), puede aparecer varias veces dentro del lockfile.
Asegúrate de reemplazar todas las coincidencias.

🧼 Paso 7: Verificar que todo funciona correctamente

Una vez actualizados los hashes, ejecuta de nuevo:

npm install
Enter fullscreen mode Exit fullscreen mode

Si el error original ya no aparece, ¡felicitaciones! 🎉
Has corregido manualmente un problema de integridad en tus dependencias.

Si aún aparece un error distinto, repite el proceso para ese nuevo
paquete.

A veces, varios paquetes presentan el mismo tipo de inconsistencia si se descargaron bajo una conexión inestable o si el lockfile fue modificado manualmente.

🧠 Entendiendo por qué ocurre este error

El error EINTEGRITY aparece cuando el checksum (hash SHA512)
calculado a partir del paquete descargado no coincide con el hash
registrado en el lockfile.

Esto puede deberse a:

  • Descargas interrumpidas o corruptas.
  • Caché dañada de NPM.
  • Lockfile desactualizado tras una actualización manual del package.json.
  • Inconsistencias entre versiones de NPM en distintos entornos (local vs CI/CD).
  • Mirrors de registro (proxies o caches) que devuelven paquetes alterados. (OJO - Ten mucho cuidado con esto 👀🧐🕵🏾).

Corregir manualmente el hash es una solución inmediata y precisa, pero también conviene revisar la causa raíz para evitar que se repita.

⚡ Alternativas si el error persiste

Si luego de corregir los hashes manualmente los errores continúan,
prueba lo siguiente:

  1. Verificar y limpiar caché de NPM

    npm cache verifylternativas si el error persiste
npm cache clean --force

  2. Eliminar node_modules y el lockfile

    rm -rf node_modules
rm -f package-lock.json
npm install

  3. Usar versiones compatibles de NPM

    npm install -g npm@latest

  4. Evitar conflictos entre gestores

    No mezcles npm y yarn en el mismo proyecto.

    Mantén un solo archivo de lock (package-lock.json o yarn.lock, nunca ambos).

🧩 Ejemplo completo resumido

1️⃣ Identificar paquete problemático - npm install
2️⃣ Buscar el hash actual - Editar package-lock.json
3️⃣ Obtener hash correcto - npm show <paquete>
4️⃣ Actualizar hash manualmente - Editar package-lock.json
5️⃣ Reinstalar dependencias - npm install
6️⃣ Verificar resultados - Revisión en consola

🧱 Buenas prácticas para prevenir estos errores

  • Usa versiones estables de Node y NPM.
    Documenta en tu proyecto las versiones recomendadas con .nvmrc o "engines" en el package.json.

  • Evita editar manualmente el lockfile, salvo para este tipo de corrección puntual.

  • Usa npm ci en entornos de integración continua (CI/CD) para instalaciones limpias y reproducibles.

  • Controla las actualizaciones automáticas: si tu editor o entorno actualiza dependencias sin sincronizar el lockfile, podrías romper la integridad.

🏁 Conclusión

Los errores de integridad en Node.js pueden parecer complejos, pero en realidad son una medida de seguridad que protege tu proyecto frente a paquetes corruptos o manipulados.

En lugar de eliminar todo el entorno, puedes resolver el problema
editando directamente el package-lock.json con el hash correcto obtenido de npm show. Así evitas reinstalaciones innecesarias y conservas la estabilidad de tu proyecto.

🚀 En resumen

  • Identifica el paquete con error.
  • Obtén el hash correcto desde npm show.
  • Reemplázalo en tu lockfile.
  • Reinstala y verifica.
  • Evita mezclar gestores y mantén tu entorno limpio.

Sencillo, directo y eficaz. 💪🏾

🎥 CTA --- Aprende más en mi canal

Si te gustó esta explicación, te invito a visitar mi canal de YouTube, donde explico paso a paso este proceso en video y comparto tutoriales sobre Node.js, NPM, y desarrollo web moderno.

👉🏾 Visita el canal aquí
(https://www.youtube.com/@untalsanders)

Top comments (0)