npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY

npm 10 y posteriores anteponen «npm error» a las líneas; npm 9 y anteriores usaban «npm ERR!». Las líneas siguientes repiten el código como errno e indican la URL con «reason: unable to get local issuer certificate».

npm (Node.js) — registry request over HTTPS

Qué significa

npm no pudo verificar el certificado TLS del registro: la cadena que recibió lleva a una raíz que no está entre las CA en las que confía Node.js. npm se ejecuta sobre Node.js, que de forma predeterminada solo confía en su lista de raíces de Mozilla integrada, así que no se usa una raíz de la empresa o del proxy instalada en el sistema operativo. La solicitud falla antes de que se descargue ningún paquete.

Por qué ocurre

• Un proxy que inspecciona TLS vuelve a firmar registry.npmjs.org

  frecuente

  En las redes corporativas, el proxy presenta certificados emitidos por su propia CA. Los navegadores confían en ella a través del sistema operativo; npm, a través de Node.js, no.

• Un registro privado con un certificado de la empresa

  frecuente

  Los registros de paquetes de Artifactory, Nexus, Verdaccio o GitHub Enterprise suelen usar un certificado de una CA interna que no está en la lista de raíces de Node.js.

• La raíz está en el almacén del sistema operativo, pero Node.js usa su propia lista

  ocasional

  update-ca-certificates, el llavero de macOS y el almacén de Windows no afectan a Node.js a menos que se le indique que use el almacén del sistema.

Cómo solucionarlo

1. 1.

   Configurar el cafile de npm

   npm config set cafile indica a npm un archivo PEM con los certificados de CA en los que confiar para las solicitudes al registro (se guarda en el .npmrc de tu usuario; --location=project o --location=global para otros ámbitos). A partir de ahí, npm solo confía en las CA de ese archivo, así que incluye también las raíces públicas si npm accede además a registros que no están detrás de tu CA.

   # npm's own setting: a PEM file with the CA(s) to trust for registry requests
   npm config set cafile /etc/ssl/private-ca/corp-root-ca.pem
   npm config get cafile

2. 2.

   Usar NODE_EXTRA_CA_CERTS

   Los certificados de este archivo se añaden a las raíces integradas de Node.js en todos los procesos de Node.js que se inicien con la variable, incluidos npm, npx y las herramientas de compilación.

   # Adds to Node.js's built-in roots for npm and every other Node.js tool in this shell
   export NODE_EXTRA_CA_CERTS=/etc/ssl/private-ca/corp-root-ca.pem
   npm install

3. 3.

   Usar el almacén de confianza del sistema operativo

   Con NODE_USE_SYSTEM_CA=1 (en las versiones de Node.js compatibles con --use-system-ca), npm confía en las raíces desplegadas por el departamento de TI en el sistema operativo.

   # Trust what the OS trusts (corporate roots deployed by IT)
   NODE_USE_SYSTEM_CA=1 npm install

4. 4.

   CI: proporcionar la CA a través del entorno

   Incluye en el repositorio la raíz de la empresa (es pública) u obtenla en el trabajo, y define NODE_EXTRA_CA_CERTS para los pasos que ejecutan npm.

   # CI job (GitHub Actions syntax): provide the CA to npm without touching the image
   env:
     NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/certs/corp-root-ca.pem
   steps:
     - run: npm ci

5. 5.

   Diagnóstico temporal: --strict-ssl=false para un solo comando

   Desactiva la verificación de certificados en las solicitudes al registro. Confirma el diagnóstico, pero permite que cualquiera en la ruta sustituya paquetes, que después ejecutan scripts de instalación en tu equipo; nunca lo dejes en .npmrc.

   # Temporary diagnostic for one command only, never in .npmrc
   npm install --strict-ssl=false

← Explorar toda la base de datos de errores de firma