unable to get local issuer certificate

Avec fetch(), le message est la cause de « TypeError: fetch failed » ; npm signale la même situation sous la forme « npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY ». Si le serveur n’envoie que son certificat feuille, Node.js signale à la place « unable to verify the first certificate ».

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

Ce que cela signifie

Le serveur a envoyé une chaîne (certificat feuille et certificat intermédiaire), mais le certificat situé à son sommet a été émis par une racine à laquelle Node.js ne fait pas confiance. Par défaut, Node.js ne fait confiance qu’à la liste de racines Mozilla compilée dans le binaire, et non au magasin de certificats du système d’exploitation : une racine d’entreprise installée sur la machine lui reste donc invisible, sauf si vous demandez à Node.js d’utiliser ce magasin.

Pourquoi cela se produit

• Une AC d’entreprise ou privée

  fréquente

  Les API internes, les environnements de préproduction et les maillages de services utilisent des racines absentes de la liste Mozilla embarquée par Node.js.

• Un proxy d’inspection TLS

  fréquente

  Sur les réseaux d’entreprise, les proxys d’interception re-signent les sites publics avec une racine d’entreprise ; lorsque le proxy n’envoie que son certificat intermédiaire émetteur, Node.js signale ce code plutôt que « self-signed certificate in certificate chain ».

• Node.js ignore par défaut le magasin de confiance du système d’exploitation

  occasionnelle

  Installer la racine avec update-ca-certificates, dans le magasin Windows ou dans le trousseau macOS corrige curl et les navigateurs, mais pas Node.js, sauf si --use-system-ca ou NODE_USE_SYSTEM_CA=1 est utilisé.

Comment corriger l’erreur

1. 1.

   NODE_EXTRA_CA_CERTS

   Indique à Node.js un fichier PEM dont les certificats s’ajoutent aux racines intégrées. La variable est lue une seule fois, au démarrage du processus : l’exporter dans une application déjà lancée n’a donc aucun effet.

   # 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.

   Utiliser le magasin du système d’exploitation

   --use-system-ca (ou NODE_USE_SYSTEM_CA=1 dans l’environnement) amène Node.js à faire confiance aux certificats approuvés par le système d’exploitation, c’est-à-dire à ceux que gèrent les services informatiques.

   # 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.

   Définir la liste d’AC par défaut dans le code

   tls.setDefaultCACertificates() remplace la liste par défaut pour les connexions ouvertes ensuite par https, tls et fetch ; combinez les valeurs par défaut existantes avec votre racine, comme le montre l’exemple.

   // 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.

   Faire confiance à la racine pour un seul agent

   L’option ca d’un agent ou de tls.connect() remplace les racines par défaut pour ces connexions : incluez donc tls.rootCertificates si le même agent communique aussi avec des hôtes publics.

   // 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());

← Parcourir toute la base de données des erreurs de signature