Zscaler Root Certificate: Why Developer Tools Break and How to Fix Them
.jpeg)
Quick answer: Developer tools break behind Zscaler because many of them keep their own certificate trust store instead of using the operating system's. When Zscaler inspects TLS, it presents a certificate signed by its own CA, and a tool that doesn't trust that CA fails with errors like x509: certificate signed by unknown authority. The fix is to export the Zscaler root certificate and point each tool at it, or bypass inspection for developer traffic. This guide shows both.
If you run Zscaler for engineers, you've seen the tickets: npm install fails, pip can't reach PyPI, Git won't clone, a Docker build dies halfway. It's almost never the network. It's trust. This post is part of our Zscaler admin guide. For how inspection itself works, see Zscaler ZIA SSL inspection; we'll stick to fixes here.
Last updated: November 2026
Why developer tools fail behind Zscaler
Zscaler says it plainly: many development tools "do not use the default system certificate store or do not trust Zscaler's certificates." Some apps maintain their own application trust store, so they can't validate the interception certificate, and others use certificate pinning (Zscaler blog).
Your browser is fine because the Zscaler root certificate was pushed to the OS store. Node, Python, Java, Git, and Docker containers often look somewhere else. Docker documents the typical error:
x509: certificate signed by unknown authorityStep 1: Get the Zscaler root certificate
The easiest way is to export it from a machine where it's already installed. Docker's guide walks through Chrome (Docker docs):
- Open
chrome://certificate-manager/. - Under Local certificates, select View imported certificates.
- Find the Zscaler root certificate, often labeled Zscaler Root CA.
- Export it in ASCII PEM format.
- Confirm the file contains
-----BEGIN CERTIFICATE-----and-----END CERTIFICATE-----.
Store it somewhere your team and build systems can reach, like an artifact repository or a Git repo, so nobody downloads a random copy off a forum.
Step 2: Point each tool at it
Each tool has its own setting. These come from Zscaler's own developer guidance (Zscaler blog) and Docker's docs. Zscaler's help center covers 20 or more additional tools, including Rust, Ruby, and the Azure CLI, on its page about adding a custom certificate to an application-specific trust store.
| Tool | Fix |
|---|---|
| Git | git config --global http.sslCAInfo /path/to/zscaler.crt |
| npm | npm config set cafile /path/to/zscaler.crt |
| pip | pip install --cert /path/to/zscaler.crt somepackage or export PIP_CERT=/path/to/zscaler.crt |
| Python requests | requests.get(url, verify='/path/to/zscaler.crt') |
| Java | keytool -importcert -file /path/to/zscaler.crt -alias zscaler -keystore $JAVA_HOME/lib/security/cacerts |
| Docker images | Copy the cert into the image and run update-ca-certificates at build time (below) |
One caution: pointing a tool at only the Zscaler certificate can break connections that bypass inspection. Zscaler's guidance is to build a custom CA bundle that includes the Zscaler root alongside your standard trusted CAs.
Step 3: Fix Docker builds the durable way
Docker's recommendation is to embed the certificate in the image at build time, because it removes startup configuration and gives you an auditable, consistent environment (Docker docs):
FROM debian:bookworm
COPY zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt
RUN apt-get update && \
apt-get install -y ca-certificates && \
update-ca-certificatesFor multi-stage builds, install the certificate in the final stage so the runtime image trusts it too.
The other option: bypass inspection for developer traffic
Sometimes trust-store surgery isn't worth it. Zscaler lets admins create an SSL inspection policy that bypasses traffic in its "System & Development" cloud application category, while still inspecting the rest of what developers do (Zscaler blog). For cert-pinned apps, a bypass is often the only path, since pinning rejects any substitute certificate by design.
The trade-off is visibility. Every bypass is traffic you aren't inspecting, so keep the list short and review it.
The real problem: finding the breakage before users do
Any gateway that inspects TLS needs a trusted certificate, ours included. What separates a smooth rollout from a ticket storm is how fast you find what broke.
dope.security runs SSL inspection on the device, and its SSL error notification feature surfaces traffic that breaks because of certificate pinning. Admins see the failing app and create a bypass in a few clicks, instead of reconstructing the problem from a user's screenshot. A Fortune 100 company credited that feature as one reason it scaled dope.security from 900 to more than 18,000 devices in weeks.
And because inspection is on the device, a bypass is a policy change pushed to the endpoint, not a routing change in someone else's cloud. Book a 20-minute demo to see it on your own engineering laptops.
Frequently asked questions
Where do I download the Zscaler root certificate?
The simplest route is exporting it from a managed machine that already trusts it, for example from Chrome's certificate manager in PEM format. Your Zscaler admin can also provide it from the ZIA admin portal.
Why does npm or pip fail behind Zscaler when my browser works?
Your browser uses the OS trust store, where the Zscaler root certificate is installed. npm, pip, and many other tools use their own trust store, so they don't trust the certificate Zscaler presents.
What does "x509: certificate signed by unknown authority" mean with Zscaler?
The tool received a certificate signed by Zscaler's CA and doesn't trust it. Add the Zscaler root certificate to that tool's trust store, or bypass inspection for that traffic.
Should I bypass SSL inspection for developer tools?
Only where trust-store fixes aren't practical, such as cert-pinned apps. Bypassed traffic isn't inspected, so keep bypasses narrow and review them regularly.
.jpeg)
.jpeg)
.jpeg)
