Lorixen.
EN

'Self-signed certificate in chain' on a work network? Fix it

Short answer: "self signed certificate in certificate chain" from npm, Node.js, pip or Git on an office or client network usually means the network is inspecting HTTPS traffic. A security appliance or proxy re-signs every site's certificate with the organisation's own certificate authority (CA), which your computer's browser trusts but your developer tools don't. The fix is to give each tool that organisation CA certificate, or to tell it to use the operating system's trust store. Don't switch certificate checking off with settings like NODE_TLS_REJECT_UNAUTHORIZED=0 or strict-ssl=false; that hides the problem and leaves every connection open to interception.

What's actually happening

On many company, school and client networks, outgoing HTTPS goes through a device that decrypts it, scans it and re-encrypts it. To do that without browser warnings, the organisation installs its own root CA certificate on managed computers. Browsers use the system's certificate store, so websites look normal.

Developer tools often don't. Node.js ships with its own list of trusted root CAs, Python tools commonly use a bundled list, and Git may use its own bundle depending on how it was installed. When they see a certificate signed by the organisation's CA, it isn't on their list, so the connection fails as untrusted.

That's why the same command works at home and fails at the office, or works in the browser but not in the terminal.

First, check it's inspection and not a real problem

Before changing settings, confirm the cause:

  • Does the error happen only on one network?
  • Open the same site in a browser on that network and view the certificate. If the issuer is your organisation or a security product rather than a public CA, inspection is in play.
  • Ask your IT team. They can confirm inspection and give you the correct root CA certificate, usually as a .pem or .crt file.

If the certificate is unexpected and IT doesn't recognise it, stop and treat it as a security issue.

Node.js: NODE_EXTRA_CA_CERTS or the system store

Node's documentation describes NODE_EXTRA_CA_CERTS: when set to a file of one or more PEM certificates, it extends Node's built-in root CAs with those certificates. Points to note from the docs:

  • It's read only when the Node process starts, so set it in your shell profile or service configuration, not from inside your code.
  • It's ignored if code passes its own ca option to a TLS or HTTPS client.
  • A missing or malformed file produces a warning, but otherwise no error.

Recent Node versions also offer --use-system-ca, added in v23.8.0 and extended beyond Windows and macOS in v23.9.0, which makes Node trust certificates in the operating system's store. If IT already deploys the CA to managed machines, this can be the simplest option.

Node's documentation is blunt about NODE_TLS_REJECT_UNAUTHORIZED=0: it disables certificate validation, makes TLS insecure and is strongly discouraged.

npm

npm runs on Node, so NODE_EXTRA_CA_CERTS often fixes installs too. npm also has its own cafile setting: a path to a file containing one or more CA certificates. Set it with npm config set cafile /path/to/org-ca.pem. Avoid strict-ssl=false, which turns verification off for every package download.

pip and Python tools

pip's documentation describes several options:

  • --cert, or the PIP_CERT environment variable, to point pip at a specific certificate bundle,
  • REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE, which pip also respects,
  • from pip 24.2, system certificates are used by default alongside its bundled ones, through the truststore package.

If your organisation's CA is in the system store, upgrading pip may be enough. Your own Python scripts using HTTP libraries may need the same bundle passed to them.

Git

Git's http.sslCAInfo setting names a file of certificates used to verify HTTPS servers, and the GIT_SSL_CAINFO environment variable overrides it. Set it for the hosts that need it, ideally scoped to the specific Git host rather than globally, so other connections keep their normal behaviour.

Build a proper bundle

When pointing a tool at a single file, include the full set of CAs it needs, not only your organisation's. Some settings replace the default list rather than add to it, so a file with only the company CA can break connections to sites that aren't inspected. Node's NODE_EXTRA_CA_CERTS adds to the defaults; for tools that replace them, combine a standard public CA bundle with your organisation's certificate.

Keep the file somewhere stable, document where it lives, and update it when IT rotates the certificate.

Containers and CI

Docker builds and CI jobs on the same network hit the same problem. Copy the CA certificate into the image and update its trust store, or pass the relevant environment variables at build time. Don't bake strict-ssl=false into Dockerfiles; it tends to survive long after anyone remembers why.

Node's documentation also notes that SSL_CERT_FILE is inherited by child processes, which may then trust the same CAs. That's usually what you want inside a build container, but be aware of it.

An illustrative example

A software firm in Limerick sends a developer to work on site at a client's office. On the client network, npm install, pip install and git pull all fail with certificate chain errors. The client's IT team confirms TLS inspection and provides their root CA. The developer sets NODE_EXTRA_CA_CERTS, configures pip with PIP_CERT pointing to a combined bundle, and scopes Git's sslCAInfo to the client's Git server. Nothing is switched off, and everything works again on the client network.

FAQ

Is it safe to trust the organisation's CA?

On that organisation's network, with IT's confirmation, it's the intended setup. Remove it from your tools when you leave if it's not your organisation.

Why does my browser work?

Browsers use the operating system's trust store, where IT installed the CA.

Can I just use a VPN to avoid inspection?

That's a policy question for the organisation. Ask before bypassing their network controls.

Does this affect production servers?

Only if they sit behind an inspecting proxy. Most public servers don't.

If your tools break on office or client networks and you'd like them configured properly, tell us which tools are failing.

Sources

WhatsAppBook a call