node-gyp fails to download Node headers: self signed certificate in certificate chain
gyp ERR! configure errorShort answer
Before it can compile a native add-on, node-gyp downloads the header files for your Node.js version over HTTPS. If a gateway on your network re-signs that traffic with its own root certificate, Node rejects it. Give node-gyp that root with NODE_EXTRA_CA_CERTS or --cafile, or skip the download with a headers tarball.
Fix it fast
1Find out which cause you have
Make the same kind of HTTPS request from Node.js, using the same trust store node-gyp uses. A status code means trust is fine and the cause is elsewhere. An error code means the certificate presented to Node is not trusted.
node --version node -e "fetch('https://nodejs.org/dist/index.json').then(r=>console.log(r.status)).catch(e=>console.log(e.cause?.code||e.message))"2Match what you see, then jump to its fix
- 1
The check above prints SELF_SIGNED_CERT_IN_CHAIN (or a similar certificate error), and the same request works from a home network or phone hotspotA company gateway re-signs HTTPS and its root certificate is not trustedFix - 2
You exported NODE_EXTRA_CA_CERTS and the error is still the same, or Node prints a one-time warning about the certificate fileThe variable is set, but it never reaches the Node.js process that does the downloadFix - 3
No trusted certificate is available to you (locked-down build agent, no access to the root file), but you can download files elsewhereThe build machine cannot reach nodejs.org at all, so the headers must come from a fileFix
- 1
What does the error look like?
gyp ERR! configure errorgyp ERR! stack Error: self signed certificate in certificate chain
Cause 1 of 3
A company gateway re-signs HTTPS and its root certificate is not trusted
1Check
node-gyp fetches the header tarball for the running Node.js version from nodejs.org. Behind a TLS-inspecting proxy or firewall, the certificate Node sees is signed by the company's own CA, which is not in Node's built-in list.
echo "${NODE_EXTRA_CA_CERTS:-not set}"2Fix
Get the company root certificate in PEM format from your IT team and point Node at it. NODE_EXTRA_CA_CERTS adds it to the well-known roots for every Node.js process you start from that shell, including the one node-gyp runs in. If you run node-gyp yourself, its own --cafile option replaces the default CA chain for the header download only, so that file must contain the gateway's root. If IT has already installed the root in the operating system's trust store (your browser trusts the site), Node.js 22.19 and later can read that store instead of a file.
export NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem
npm rebuild
# or, running node-gyp directly
npx node-gyp configure --cafile=/path/to/company-root-ca.pem
# or, root already in the OS trust store (Node.js 22.19+ or 24.6+)
NODE_USE_SYSTEM_CA=1 npm rebuild3Verify
Repeat the first-step request; it should now print 200. Then run the build again.
node -e "fetch('https://nodejs.org/dist/index.json').then(r=>console.log(r.status)).catch(e=>console.log(e.cause?.code||e.message))"
npx node-gyp configureConfirmed by nodejs.org
Cause 2 of 3
The variable is set, but it never reaches the Node.js process that does the download
1Check
Node reads this variable only once, when the process starts, so changing process.env inside a running process has no effect. It also ignores the variable when it runs as setuid root. If the file is missing or malformed, Node warns once and carries on without it. Check that the path exists and that the file holds PEM certificates.
test -r "$NODE_EXTRA_CA_CERTS" && grep -c 'BEGIN CERTIFICATE' "$NODE_EXTRA_CA_CERTS"
env | grep NODE_EXTRA_CA_CERTS2Fix
Export the variable in the same shell, or on the same command line, that starts the install. In CI, define it as a job-level environment variable. The file must be PEM text, with each certificate between BEGIN CERTIFICATE and END CERTIFICATE lines, and it may hold several certificates one after another.
NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem npm rebuild3Verify
Run the first-step request in the same shell and the same way the build runs; it should print 200.
NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem node -e "fetch('https://nodejs.org/dist/index.json').then(r=>console.log(r.status))"Confirmed by nodejs.org
Cause 3 of 3
The build machine cannot reach nodejs.org at all, so the headers must come from a file
1Check
Each Node.js release folder on nodejs.org holds a headers archive next to the binaries, named node-v<version>-headers.tar.gz. node-gyp can read headers from a local tarball instead of downloading them.
node -p process.versions.node2Fix
On a machine that can reach nodejs.org, download the archive for the exact version node --version prints, copy it to the build machine and pass it with --tarball. When npm starts node-gyp for you, the environment-variable form from node-gyp's README does the same.
V=$(node -p process.versions.node)
curl -O "https://nodejs.org/dist/v$V/node-v$V-headers.tar.gz"
npx node-gyp configure --tarball=./node-v$V-headers.tar.gz
# when npm runs node-gyp
export npm_package_config_node_gyp_tarball=$PWD/node-v$V-headers.tar.gz
npm rebuild3Verify
node-gyp configure should finish without opening a connection to nodejs.org, and the build files appear in the build folder.
npx node-gyp configure --tarball=./node-v$V-headers.tar.gz
ls buildConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Keep the company root certificate in a known path on every build machine and export NODE_EXTRA_CA_CERTS in the shell profile and in CI.
- Never turn certificate checking off for the whole build to get past this error; it removes the protection for every download in the process.
- Use prebuilt binaries where a package offers them, so node-gyp is not needed at install time.
- Cache the headers on build agents, or keep the headers archive for your Node.js version in an internal artifact store.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
npm rejects the certificate it gets from a company proxy
npm ERR! request to https://registry.npmjs.org/express failed, reason: self signed certificate in certificate chain
A proxy that inspects HTTPS traffic re-signs it with the company's own root certificate, which Node does not know, so npm refuses the connection.
3 causes, each with a fixBack end
Node reports that no native build was found for your platform
loaded from: <path to the package>
The package loads its native .node file through node-gyp-build.
4 causes, each with a fixBack end
ng serve says it cannot determine the project or target
Cannot determine project for command.
The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.
3 causes, each with a fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fix