Zscaler Client Connector Troubleshooting: 8 Errors Admins Hit Most
.jpeg)
Quick answer: Most Zscaler Client Connector errors come from five root causes: a failed device posture check on endpoint firewall or antivirus, certificate pinning breaking SSL inspection, captive portal detection failing on public Wi-Fi, the tunnel dropping during a network change, and bypass lists that are wrong or out of date. Start with the agent's own diagnostics: check tunnel state and authentication status in the app, then pull logs from the Client Connector before you change any policy.
New here? If you're still learning the stack, read what Zscaler Client Connector is first.
Before you touch anything: read the agent
Every troubleshooting session should start in the same place. Open the Client Connector on the affected machine and look at three things: whether the user is authenticated, whether the ZIA tunnel shows connected, and whether ZPA shows connected. Those three states, plus the network the device is on, explain most tickets before you've looked at a single log line.
Then confirm the agent version. Version drift between user groups is a quiet cause of "only some people have this problem," especially when an update ring pinned one group to an older build.
1. Zscaler endpoint FW/AV error
Symptoms. The agent shows an error referencing endpoint firewall or antivirus, ZPA access is denied, or the user is placed in a restricted posture group. The user can usually still browse, which makes the ticket confusing.
Likely cause. A device posture check is failing. Zscaler posture profiles can require an active firewall or a recognized antivirus product, and the check reads what the operating system reports. If a third-party endpoint product replaced the built-in one, the OS may no longer report the expected state, or the product may not be on Zscaler's recognized list.
What to check. Confirm what the OS itself reports (Windows Security Center on Windows, the system firewall state on macOS) and compare it against the posture profile's criteria. If you recently swapped EDR vendors, the posture profile needs updating, not the endpoint. Also check whether the third-party firewall is blocking the agent's own processes.
2. Certificate pinning breaks an application
Symptoms. One specific application fails while everything else works. You see certificate errors, TLS handshake failures, or a client that silently refuses to sign in. Common offenders are Microsoft 365 desktop apps, WebEx, Dropbox, and developer tooling like package managers and CLI tools.
Likely cause. The application pins its expected certificate. SSL inspection substitutes Zscaler's certificate, the app compares it to the pinned value, and it refuses the connection. This is the application working as designed.
What to check. Confirm it's pinning and not a missing root certificate, which produces a similar error. If the Zscaler root is trusted at the OS level and the app still fails, it's pinning. The fix is a bypass entry, not a certificate fix. For tools with their own certificate store (many developer utilities), the fix is adding the certificate to that store instead.
This category never fully goes away in a cloud proxy architecture, and it's worth knowing that up front.
3. Captive portal detection fails
Symptoms. A user at a hotel, airport, or conference can't get online at all. The agent shows it's trying to connect. The portal login page never appears, or it appears and the network still doesn't work after sign-in.
Likely cause. The agent tries to forward traffic before the device has actually joined the network. Captive portals intercept HTTP requests to a probe URL, and if that probe is itself being forwarded or blocked, the operating system never realizes a portal exists.
What to check. Verify captive portal detection is enabled in the app profile and that the portal detection URLs aren't caught by your forwarding PAC. Make sure the OS-level connectivity probe hosts are excluded from forwarding. As a workaround for a stuck user, the agent's temporary disable (if your policy allows it, with the disable password) lets them authenticate to the portal, after which the tunnel comes back.
4. Tunnel drops when the network changes
Symptoms. A user moves from office Wi-Fi to a phone hotspot, wakes a laptop from sleep, or connects a corporate VPN, and traffic stops for 10 to 60 seconds or until they restart the app.
Likely cause. Forwarding profile re-evaluation. When the network changes, the agent re-runs trusted network detection and may switch forwarding methods mid-flight. If your trusted network criteria are ambiguous (for example a DNS suffix that also appears on a home router, or a hostname that resolves both internally and externally), the agent can flap between profiles.
What to check. Tighten trusted network criteria so they're unambiguous, ideally combining a DNS search domain with an internal hostname that resolves to a specific address only inside your network. Then check the VPN trusted network profile separately, because a corporate VPN that already carries traffic to Zscaler plus an agent that also tunnels produces double encapsulation and unpredictable MTU behavior.
5. Slow first byte for users far from a point of presence
Symptoms. Pages eventually load but feel heavy. Users in one region complain, users near a Zscaler data center don't. Video calls are fine (they're usually bypassed) while everything else drags.
Likely cause. Distance. Every request forwards to a Service Edge node before reaching its destination. Measured cloud-proxy latency runs roughly 40 to 80 ms when a user is near a point of presence and 150 to 400 ms when they're far from one.
What to check. Confirm which node the user is actually landing on, because a misconfigured application PAC can send someone to a node on the wrong continent. Check whether recently enabled inspection modules made it worse, since Gartner has cited a 10-20% throughput drop on cloud proxies as modules stack. For users in China, confirm whether they're licensed for China Premium or Plus, which are paid uplifts.
Be honest with yourself on this one. If the node assignment is correct and the modules are necessary, you've found an architecture limit, not a misconfiguration.
6. Bypass lists that are wrong, stale, or in the wrong file
Symptoms. Traffic you expected to bypass gets inspected, or traffic you expected to inspect goes direct and never appears in logs. Policy looks correct in the console.
Likely cause. Zscaler has several places a bypass can live: the forwarding PAC, the application PAC, SSL inspection exemptions, and ZPA application segments. An entry in the wrong one produces exactly this confusion, because each file answers a different question.
What to check. Decide what you're actually trying to do. To skip Zscaler entirely, that's the forwarding PAC. To reach Zscaler without decryption, that's an SSL inspection exemption. To route to a private app, that's a ZPA application segment. Also check for wildcards broader than intended and duplicates that contradict each other across files. Keep a changelog: PAC files accumulate entries from people who left three years ago.
7. Driver, OS update, and agent version conflicts
Symptoms. After a macOS or Windows update, the agent fails to start, loses its network extension, or the tunnel comes up but no traffic flows. Sometimes only on one hardware model or one OS build.
Likely cause. The agent installs low-level components: a network or system extension on macOS, filter drivers on Windows. Major OS updates can deactivate or require re-approval of those components. Third-party VPN clients and some EDR agents install at the same layer and can conflict.
What to check. On macOS, confirm the system extension is approved and that your MDM configuration profile pre-approves it, so the user isn't relying on a prompt they dismissed. On Windows, confirm the agent's services are running and that no other product has taken the same filter position. Then check your update ring: pinning an old agent version through a major OS release is a common way to break a fleet on a predictable date.
8. Collecting Zscaler diagnostics correctly
Symptoms. You open a support case and get asked for logs you didn't capture, then have to reproduce the issue two days later.
Likely cause. Logs were collected after a restart, which cleared the state that mattered.
What to check. Reproduce the problem first, then collect. Use the agent's built-in log export while the failure is still present, and raise logging to a debug level in the app profile beforehand if the default is too thin. Capture the exact timestamp, the user's public IP, the Service Edge node in use, and the URL or application that failed. A packet capture taken at the same moment turns a week-long ticket into a one-reply ticket. Write that up as a four-line runbook so your help desk collects the right artifacts every time.
Which of these are configuration problems and which are architectural?
This distinction saves you a lot of wasted effort.
Configuration problems you can fully solve: the endpoint FW/AV posture error, captive portal detection, tunnel flapping on network change, bypass list placement, driver and version conflicts, and diagnostics collection. Six of the eight. Write better trusted network criteria, tighten posture profiles, standardize agent versions, and these mostly go away.
Architectural limits you can only manage: certificate pinning and distance latency. Cert-pinned applications including Microsoft 365, WebEx, and Dropbox can't be inspected by a proxy that substitutes certificates, so you bypass them and accept the visibility gap. And a forwarding architecture always pays the round trip, which is why a user far from a point of presence stays slow no matter how well you tune.
There's also a dependency you can't configure away. On October 25, 2022, a Zscaler outage produced 100% packet loss. When the inspection point is the only path to the internet, its uptime is your uptime.
How an on-device architecture changes these categories
dope.security takes a different approach: the SSL proxy runs on the endpoint in dope.SWG, inspects locally, and then the request goes straight to its destination. No node in the middle means no distance penalty, which removes the slow-first-byte category outright, and it's why performance runs up to 4x that of legacy proxy SWGs while the agent uses under 100 MB of RAM.
On certificate pinning, the gap doesn't disappear (no proxy can inspect a pinned app), but the operational pain does. dope.security surfaces the SSL errors that cert pinning produces, so an admin sees exactly which application broke and creates the bypass in a few clicks instead of correlating a user complaint with a packet capture.
Policy pushes instantly to all devices regardless of location, and fallback mode keeps cached policies enforcing when connectivity drops. It's Mac native for Apple Silicon and Intel plus Windows with identical features on both, and pricing is public at $60 per device per year.
If your troubleshooting queue is mostly architecture and not configuration, book a 20-minute demo at calendly.com/dopesecurity/demo or start a free trial with Google or Microsoft sign-in.
Frequently Asked Questions
What causes the Zscaler endpoint FW/AV error?
A device posture check is failing. Zscaler posture profiles can require an active firewall or a recognized antivirus product, and the check reads what the operating system reports. Swapping EDR vendors, or a third-party firewall blocking the agent's own processes, both produce this error.
Why is Zscaler Client Connector not connecting?
Check authentication first, then the network. The most common causes are a failed identity provider handshake, a captive portal the device hasn't signed into yet, ambiguous trusted network criteria causing profile flapping, or a system extension on macOS that lost approval after an OS update.
How do I collect Zscaler diagnostics?
Reproduce the problem first, then export logs from the agent while the failure is still present. Raise the logging level in the app profile beforehand if the default is too thin, and record the timestamp, the user's public IP, the Service Edge node in use, and the failing URL or application.
Why do some apps break when Zscaler SSL inspection is on?
Certificate pinning. The application expects a specific certificate, SSL inspection substitutes Zscaler's, and the app refuses the connection. Microsoft 365, WebEx, and Dropbox are the commonly cited examples. The fix is a bypass entry, not a certificate change.
Why is Zscaler slow for some users and not others?
Distance to the nearest Service Edge node. Measured cloud-proxy latency is roughly 40 to 80 ms near a point of presence and 150 to 400 ms far from one. Gartner has also cited a 10-20% throughput drop as inspection modules stack, so enabling more policy makes it worse.
Where should a Zscaler bypass go: the PAC file or SSL exemptions?
It depends on the goal. To skip Zscaler entirely, use the forwarding PAC. To reach Zscaler without decryption, use an SSL inspection exemption. To route to a private application, use a ZPA application segment. Putting an entry in the wrong file is one of the most common Zscaler Client Connector errors.
Does a macOS update break Zscaler Client Connector?
It can. The agent installs a system extension, and major macOS updates may deactivate it or require re-approval. Pre-approve the extension through an MDM configuration profile so users never see a prompt, and avoid pinning an old agent version across a major OS release.
Can any proxy inspect certificate-pinned applications?
No. Certificate pinning rejects any substituted certificate by design, so every proxy-based architecture has this gap and handles it with bypasses. dope.security surfaces the resulting SSL errors in the console so admins can identify the affected application and create a bypass in a few clicks.
.jpeg)
.jpeg)
