npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY

O npm 10 e posteriores iniciam as linhas com “npm error”; o npm 9 e anteriores usavam “npm ERR!”. As linhas seguintes repetem o código como errno e trazem a URL com “reason: unable to get local issuer certificate”.

npm (Node.js) — registry request over HTTPS

O que significa

O npm não conseguiu verificar o certificado TLS do registro: a cadeia recebida leva a uma raiz que não está entre as CAs em que o Node.js confia. O npm roda sobre o Node.js, que por padrão confia só na lista de raízes da Mozilla embutida nele, então uma raiz da empresa ou do proxy instalada no sistema operacional não é usada. A requisição falha antes de qualquer pacote ser baixado.

Por que acontece

• Um proxy com inspeção de TLS reassina o registry.npmjs.org

  comum

  Em redes corporativas, o proxy apresenta certificados emitidos pela própria CA. Os navegadores confiam nela por meio do sistema operacional; o npm, por meio do Node.js, não.

• Um registro privado com um certificado da empresa

  comum

  Artifactory, Nexus, Verdaccio ou registros de pacotes do GitHub Enterprise costumam usar um certificado de uma CA interna que não está na lista de raízes do Node.js.

• A raiz está no repositório do sistema operacional, mas o Node.js usa a própria lista

  ocasional

  O update-ca-certificates, o chaveiro do macOS e o repositório de certificados do Windows não afetam o Node.js, a menos que ele seja instruído a usar o repositório do sistema.

Como corrigir

1. 1.

   Definir o cafile do npm

   O comando npm config set cafile aponta o npm para um arquivo PEM com os certificados de CA em que confiar nas requisições ao registro (a configuração fica gravada no .npmrc do seu usuário; --location=project ou --location=global para outros escopos). A partir daí, o npm confia só nas CAs desse arquivo; por isso, inclua também as raízes públicas se o npm também acessar registros que não estão atrás da sua 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

   Os certificados desse arquivo são somados às raízes embutidas do Node.js em todo processo Node.js iniciado com a variável, inclusive npm, npx e ferramentas de build.

   # 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 o trust store do sistema operacional

   Com NODE_USE_SYSTEM_CA=1 (nas versões do Node.js que aceitam --use-system-ca), o npm confia nas raízes que a TI distribuiu no sistema operacional.

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

4. 4.

   CI: fornecer a CA pelo ambiente

   Faça commit da raiz da empresa (ela é pública) ou baixe-a no job e defina NODE_EXTRA_CA_CERTS nas etapas que executam o 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 temporário: --strict-ssl=false em um único comando

   Desativa a verificação de certificados nas requisições ao registro. Isso confirma o diagnóstico, mas permite que qualquer um no caminho substitua pacotes, que então executam scripts de instalação na sua máquina; nunca mantenha essa opção no .npmrc.

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

← Ver toda a base de erros de assinatura