unable to get local issuer certificate

Com fetch(), a mensagem é a causa de “TypeError: fetch failed”; o npm informa a mesma situação como “npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY”. Se o servidor envia só o certificado folha, o Node.js informa “unable to verify the first certificate” em vez disso.

Node.js tls / https / fetch — code UNABLE_TO_GET_ISSUER_CERT_LOCALLY (OpenSSL X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY, 20)

O que significa

O servidor enviou uma cadeia (certificado folha e intermediário), mas o certificado do topo foi emitido por uma raiz em que o Node.js não confia. Por padrão, o Node.js confia só na lista de raízes da Mozilla compilada no binário, e não no repositório do sistema operacional, então uma raiz da empresa instalada na máquina é invisível para ele, a menos que você instrua o Node.js a usá-la.

Por que acontece

• Uma CA da empresa ou privada

  comum

  APIs internas, ambientes de homologação e service meshes usam raízes que não estão na lista da Mozilla embutida no Node.js.

• Um proxy com inspeção de TLS

  comum

  Em redes corporativas, proxies que interceptam o tráfego reassinam sites públicos com uma raiz da empresa; quando o proxy envia só o intermediário emissor, o Node.js informa este código em vez de “self-signed certificate in certificate chain”.

• O Node.js ignora o trust store do sistema operacional por padrão

  ocasional

  Instalar o certificado raiz com update-ca-certificates, no repositório do Windows ou no chaveiro do macOS corrige o curl e os navegadores, mas não o Node.js, a menos que se use --use-system-ca ou NODE_USE_SYSTEM_CA=1.

Como corrigir

1. 1.

   Variável NODE_EXTRA_CA_CERTS

   Aponta o Node.js para um arquivo PEM cujos certificados são somados às raízes embutidas. A variável é lida uma vez, quando o processo inicia, então exportá-la dentro de um aplicativo em execução não tem efeito.

   # Adds to Node's built-in roots; read once at start-up, so set it before node starts
   export NODE_EXTRA_CA_CERTS=/etc/ssl/private-ca/corp-root-ca.pem
   node app.js

2. 2.

   Usar o repositório do sistema operacional

   Com --use-system-ca (ou NODE_USE_SYSTEM_CA=1 no ambiente), o Node.js confia nos certificados em que o sistema operacional confia, ou seja, os que os departamentos de TI gerenciam.

   # Trust what the operating system trusts (Windows store, macOS Keychain, Linux bundle)
   node --use-system-ca app.js
   # or, for tools that start node themselves (npm scripts, CLIs):
   NODE_USE_SYSTEM_CA=1 npx some-cli

3. 3.

   Definir a lista padrão de CAs no código

   A função tls.setDefaultCACertificates() substitui a lista padrão nas conexões seguintes feitas por https, tls e fetch; combine os certificados padrão existentes com a sua raiz, como no exemplo.

   // In code, before the first request: keep the default roots and add yours.
   // Applies to https, tls and fetch. Available in current Node.js 22 and 24 releases.
   import tls from "node:tls";
   import fs from "node:fs";
   
   tls.setDefaultCACertificates([
     ...tls.getCACertificates("default"),
     fs.readFileSync("/etc/ssl/private-ca/corp-root-ca.pem", "utf8"),
   ]);

4. 4.

   Confiar na raiz em um único agente

   A opção ca de um agente ou de tls.connect() substitui as raízes padrão nessas conexões, então inclua tls.rootCertificates se o mesmo agente também se comunica com hosts públicos.

   // Per-agent trust: note that "ca" REPLACES the default roots, so append them
   import https from "node:https";
   import tls from "node:tls";
   import fs from "node:fs";
   
   const agent = new https.Agent({ ca: [...tls.rootCertificates, fs.readFileSync("corp-root-ca.pem", "utf8")] });
   https.get("https://api.example.com/", { agent }, (res) => res.resume());

← Ver toda a base de erros de assinatura