code: 'DEPTH_ZERO_SELF_SIGNED_CERT'

Node.js 24.22 imprime el mensaje como «self-signed certificate; if the root CA is installed locally, try running Node.js with --use-system-ca»; las versiones anteriores imprimen solo «self-signed certificate» («self signed certificate» antes de Node.js 17). El código es la parte estable por la que buscar.

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

Qué significa

El certificado del servidor es autofirmado (es su propio emisor, la «profundidad cero» de la cadena) y no está en el conjunto de certificados de confianza de Node.js. Node.js lo indica con el mensaje «self-signed certificate» y el código DEPTH_ZERO_SELF_SIGNED_CERT. Es típico de servidores de desarrollo locales, herramientas internas y servicios que siguen usando el certificado generado durante la instalación.

Por qué ocurre

• Un servidor HTTPS local con un certificado generado

  frecuente

  Los servidores de desarrollo (Vite o webpack con https, pasarelas de API locales, entornos de docker-compose) crean un certificado autofirmado en el que no confían los scripts de Node.js, las pruebas ni el código SSR.

• Herramientas internas y dispositivos dedicados

  frecuente

  Servicios autoalojados (Jenkins, Grafana, Elasticsearch, páginas de administración de routers o NAS) a los que nunca se les instaló un certificado emitido por una CA.

• Un proxy sirve su certificado predeterminado integrado

  ocasional

  Los controladores de ingress y los proxies inversos presentan un certificado predeterminado autofirmado cuando ningún certificado configurado coincide con el nombre solicitado.

Cómo solucionarlo

1. 1.

   Confiar en este certificado concreto para un solo agente

   Pasa el certificado del servidor como ca. Solo se acepta este certificado, y las comprobaciones del nombre de host y de la validez siguen activas; ten en cuenta que ca sustituye las raíces predeterminadas en este 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.

   Añadir el certificado para todo el proceso

   NODE_EXTRA_CA_CERTS funciona igual para https, tls y fetch(), y no requiere cambios en el 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 una CA local para desarrollo

   Una raíz local en la que se confía una sola vez (mkcert, step-ca) emite certificados debidamente firmados para cada host de desarrollo y evita las excepciones certificado 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 temporal: rejectUnauthorized: false

   Acepta cualquier certificado en ese agente, incluido el de un atacante. Solo es aceptable para una comprobación local rápida; nunca en código que vaya a producción.

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

← Explorar toda la base de datos de errores de firma