npm ERR! code DEPTH_ZERO_SELF_SIGNED_CERT

What This Error Means

npm received a self-signed certificate from the registry or proxy.

How to Fix It

1. Confirm which registry host npm is calling: npm config get registry.
2. Check for proxy settings: npm config get proxy and npm config get https-proxy.
3. Check TLS config: npm config get strict-ssl and npm config get cafile.
4. Run a quick registry check: npm ping.
5. If this only fails on your office/VPN but works on a hotspot, treat it as corporate TLS interception until proven otherwise.
6. Quick confirmation (insecure, temporary): run once with npm --strict-ssl=false <command>. If it works, fix CA trust instead of leaving SSL checks disabled.
7. Alternative temporary config toggle (insecure): npm config set strict-ssl false, retry once, then immediately revert: npm config set strict-ssl true.
8. Alternative one-off (insecure): run once with NODE_TLS_REJECT_UNAUTHORIZED=0 (do not use in CI, remove afterward).
9. Proper fix: trust the CA that is signing the certificate chain.
10. If you are behind a corporate TLS proxy, export the corporate root CA and configure npm: npm config set cafile /path/to/corp-ca.pem.
11. In CI, prefer NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem so Node trusts the internal CA without changing global npm config.
12. If you control the registry/proxy, ensure it serves the full certificate chain (leaf + intermediates).
13. Inspect the served chain: openssl s_client -showcerts -connect <host>:443 -servername <host> </dev/null.
14. Retry with npm --verbose and keep the full output for troubleshooting.

Why It Happens

• A corporate proxy/VPN is intercepting HTTPS and presenting a certificate signed by an internal CA that Node does not trust.
• Your registry (or proxy registry) is serving an incomplete chain (missing intermediate CA certificates).
• System time is incorrect, which can make otherwise valid certificates fail validation.
• Node/npm is using a CA trust store that does not include the required issuer certificates.

How to Verify

1. Run npm ping (same network, same registry) and confirm it succeeds.
2. Re-run the original command and confirm the TLS error no longer appears.

Manual certificate validation

1. Confirm the failing host matches your registry: npm config get registry.
2. If you control the registry/proxy, ensure it serves the full certificate chain (leaf + intermediates).
3. Inspect the served chain: openssl s_client -showcerts -connect <host>:443 -servername <host> </dev/null.
4. If curl works but npm fails, the issue is usually Node's CA trust (fix with NODE_EXTRA_CA_CERTS / cafile).
5. If you need a quick confirmation, disable strict SSL for one retry only, then revert it.

Common CLI Output

npm ERR! code DEPTH_ZERO_SELF_SIGNED_CERT

How npm verifies TLS certificates

1. npm uses Node.js for HTTPS. Certificate validation happens in Node's TLS stack.
2. The server must provide a valid chain to a trusted root CA, and the certificate must match the hostname.
3. Proxies that intercept TLS must be trusted by adding their root CA to the client trust store (or configuring cafile).

Prevention Tips

• Bake your corporate root CA into CI runner images (or distribute via configuration management).
• Use a registry/proxy that serves a complete, valid certificate chain.
• Keep Node.js and npm updated so you get current CA bundles and TLS defaults.

Where This Can Be Triggered

// used by the ping and doctor commands
const npmFetch = require('npm-registry-fetch')
module.exports = async (flatOptions) => {
  const res = await npmFetch('/-/ping', { ...flatOptions, cache: false })
  return res.json().catch(() => ({}))
}