code: 'DEPTH_ZERO_SELF_SIGNED_CERT'

O Node.js 24.22 imprime a mensagem como “self-signed certificate; if the root CA is installed locally, try running Node.js with --use-system-ca”; versões mais antigas imprimem só “self-signed certificate” (“self signed certificate” antes do Node.js 17). O código é a parte estável para buscar.

Node.js tls / https / fetch — error.message "self-signed certificate" (OpenSSL X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT, 18)

O que significa

O certificado do servidor é autoassinado (ele é o próprio emissor, a “profundidade zero” da cadeia) e não está no conjunto de certificados confiáveis do Node.js. O Node.js o informa com a mensagem “self-signed certificate” e o código DEPTH_ZERO_SELF_SIGNED_CERT. É típico de servidores de desenvolvimento locais, ferramentas internas e serviços que ainda usam o certificado gerado na instalação.

Por que acontece

• Um servidor HTTPS local com um certificado gerado

  comum

  Servidores de desenvolvimento (Vite ou webpack com https, gateways de API locais, stacks do docker-compose) criam um certificado autoassinado em que scripts, testes e código SSR do Node.js não confiam.

• Ferramentas internas e appliances

  comum

  Serviços auto-hospedados (Jenkins, Grafana, Elasticsearch, páginas de administração de roteadores ou NAS) que nunca receberam um certificado emitido por uma CA.

• Um proxy apresenta o próprio certificado padrão embutido

  ocasional

  Controladores de ingress e proxies reversos apresentam um certificado padrão autoassinado quando nenhum certificado configurado corresponde ao nome solicitado.

Como corrigir

1. 1.

   Confiar neste certificado em um único agente

   Passe o certificado do servidor como ca. Só esse certificado é aceito, e as verificações de nome do host e de validade continuam ativas; observe que ca substitui as raízes padrão nesse agente.

   // Trust exactly this certificate for this agent (hostname and dates are still checked)
   import https from "node:https";
   import fs from "node:fs";
   
   const agent = new https.Agent({ ca: fs.readFileSync("localhost.pem") });
   https.get("https://localhost:8443/", { agent }, (res) => res.resume());

2. 2.

   Adicionar o certificado para o processo inteiro

   A variável NODE_EXTRA_CA_CERTS funciona igualmente para https, tls e fetch() e não exige mudanças no código.

   # Whole process, including fetch(): add the certificate to the trusted set
   NODE_EXTRA_CA_CERTS=./localhost.pem node app.js

3. 3.

   Usar uma CA local para desenvolvimento

   Uma raiz local em que você confia uma única vez (mkcert, step-ca) emite certificados assinados corretamente para todos os hosts de desenvolvimento e evita exceções por certificado.

   # Development: a local CA (mkcert) instead of one-off self-signed certificates
   mkcert -install && mkcert localhost 127.0.0.1
   NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" node app.js

4. 4.

   Diagnóstico temporário: rejectUnauthorized: false

   Aceita qualquer certificado nesse agente, inclusive o de um atacante. Aceitável só para uma verificação local rápida; nunca em código que vai para produção.

   // Temporary diagnostic in a test only: accepts ANY certificate on this agent
   const agent = new https.Agent({ rejectUnauthorized: false });

← Ver toda a base de erros de assinatura