unable to get local issuer certificate

Bei fetch() ist die Meldung die Ursache von „TypeError: fetch failed“; npm meldet denselben Zustand als „npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY“. Sendet der Server nur sein Leaf-Zertifikat, meldet Node.js stattdessen „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)

Was der Fehler bedeutet

Der Server hat eine Kette gesendet (Leaf- und Zwischenzertifikat), aber das oberste Zertifikat darin wurde von einem Root-Zertifikat ausgestellt, dem Node.js nicht vertraut. Standardmäßig vertraut Node.js nur der in die Binärdatei kompilierten Root-Liste von Mozilla, nicht dem Trust Store des Betriebssystems; ein auf dem Rechner installiertes Root-Zertifikat der Firma bleibt für Node.js daher unsichtbar, solange du Node.js nicht anweist, es zu verwenden.

Warum der Fehler auftritt

• Eine Firmen-CA oder eine private CA

  häufig

  Interne APIs, Staging-Umgebungen und Service Meshes verwenden Root-Zertifikate, die nicht in der mitgelieferten Mozilla-Liste von Node.js stehen.

• Ein Proxy mit TLS-Inspektion

  häufig

  In Firmennetzwerken signieren abfangende Proxys öffentliche Websites mit einem Root-Zertifikat der Firma neu; sendet der Proxy nur sein ausstellendes Zwischenzertifikat, meldet Node.js diesen Code statt „self-signed certificate in certificate chain“.

• Node.js ignoriert standardmäßig den Trust Store des Betriebssystems

  gelegentlich

  Installierst du das Root-Zertifikat mit update-ca-certificates, im Windows-Zertifikatsspeicher oder im macOS-Schlüsselbund, behebt das den Fehler für curl und Browser, aber nicht für Node.js – es sei denn, du verwendest --use-system-ca oder NODE_USE_SYSTEM_CA=1.

So behebst du den Fehler

1. 1.

   NODE_EXTRA_CA_CERTS

   Verweist Node.js auf eine PEM-Datei, deren Zertifikate zu den eingebauten Root-Zertifikaten hinzugefügt werden. Die Variable wird einmal beim Start des Prozesses gelesen; sie innerhalb einer laufenden App zu exportieren, hat daher keine Wirkung.

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

   Trust Store des Betriebssystems verwenden

   --use-system-ca (oder NODE_USE_SYSTEM_CA=1 in der Umgebung) lässt Node.js den Zertifikaten vertrauen, denen das Betriebssystem vertraut – und genau diese verwalten IT-Abteilungen.

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

   Standard-CA-Liste im Code setzen

   tls.setDefaultCACertificates() ersetzt die Standardliste für spätere Verbindungen über https, tls und fetch; kombiniere die vorhandenen Standardeinträge wie gezeigt mit deinem Root-Zertifikat.

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

   Dem Root-Zertifikat für einen einzelnen Agenten vertrauen

   Die Option ca eines Agenten oder von tls.connect() ersetzt die Standard-Root-Zertifikate für diese Verbindungen; nimm deshalb tls.rootCertificates mit auf, wenn derselbe Agent auch mit öffentlichen Hosts kommuniziert.

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

← Gesamte Signaturfehler-Datenbank durchsuchen