npm ERR! code HOSTNAME_MISMATCH

What This Error Means

npm connected to a host whose certificate doesn't match the hostname (CN/SAN mismatch).

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. If you use scoped registries, verify .npmrc mapping (example: @your-scope:registry=...).
5. If you use a private registry, ensure the certificate includes the exact hostname you use in .npmrc.
6. If you control the registry/proxy, ensure it serves the full certificate chain (leaf + intermediates).
7. Inspect the served chain: openssl s_client -showcerts -connect <host>:443 -servername <host> </dev/null.
8. Quick confirmation (insecure, temporary): run once with npm --strict-ssl=false <command>. If it works, fix CA trust instead of leaving SSL checks disabled.
9. Alternative temporary config toggle (insecure): npm config set strict-ssl false, retry once, then immediately revert: npm config set strict-ssl true.
10. Alternative one-off (insecure): run once with NODE_TLS_REJECT_UNAUTHORIZED=0 (do not use in CI, remove afterward).
11. Proper fix: trust the CA that is signing the certificate chain.
12. 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.
13. In CI, prefer NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem so Node trusts the internal CA without changing global npm config.
14. Retry with npm --verbose and keep the full output for troubleshooting.

Why It Happens

• The registry hostname does not match the certificate (CN/SAN mismatch).
• A proxy is presenting a certificate for a different hostname.
• You are hitting the wrong registry host due to .npmrc scope mapping or an env override.

How to Verify

1. Run npm ping and confirm it succeeds.
2. Re-run the original command and confirm HOSTNAME_MISMATCH is gone.

Manual certificate validation

1. Inspect SANs for the registry cert: openssl s_client -connect <host>:443 -servername <host> </dev/null | openssl x509 -noout -text.
2. Confirm the hostname appears under Subject Alternative Name (SAN).

Common CLI Output

npm ERR! code HOSTNAME_MISMATCH

How npm verifies TLS certificates

1. npm uses Node.js for HTTPS. Node verifies the certificate chain and checks that the certificate matches the hostname you requested.
2. If the hostname does not match, the connection is rejected even if the certificate is otherwise trusted.

Prevention Tips

• Avoid registry host aliases that do not match the deployed certificate.
• Keep .npmrc scope mappings explicit and reviewed.

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(() => ({}))
}