Analyzing Zscaler Client Connector logs: from export to finding

Ready to check your own bundle? Open the free Log Analyzer.

ZCC logs are a goldmine, but hard work to read

When a user reports that an application is unreachable or sign-in keeps hanging, the answer is often already in the logs of the Zscaler Client Connector (ZCC). Several components log in parallel there: tunnel establishment, service state, updates and further processes are spread across files such as ZSATunnel.log, ZSAService.log or ZSAUpm.log.

That is exactly what makes manual analysis tedious. An exported log bundle contains many files, rotated archives and tens of thousands of lines. The relevant patterns are cryptic, span multiple files and have to be correlated in time. In everyday help desk work there is rarely time for that, and the experience of knowing which line points to which cause is unevenly distributed.

Path 1: upload the log bundle and let it be evaluated

Log Analyzer in CentaurNexus takes over this step. The upload workflow:

In addition, an overview summarizes the bundle metadata: ZCC version, operating system, Z-Tunnel version, covered time range and the counters for errors and warnings. That makes clear at a glance which client state and time window the analysis covers.

Which failure patterns are detected

The analysis looks for known patterns and assigns them to categories, among others: authentication loops and login failures, disrupted Z-Tunnel connections, failed DNS resolution, PAC file errors, unmet device posture, SSL and certificate errors, local AV or firewall blocking of the ZPA loopback packets, detected captive portals and stuck ZCC upgrades.

Each category comes with a recommendation naming the next verification step: IdP and SAML configuration including system time for authentication loops, the network path to the Service Edge for tunnel disruptions, or the trust store chain for certificate errors. The operator does not start at line one, but at the most likely lever.

Three cases, line by line

The lines below come from the anonymised demo bundle the Log Analyzer ships with. They show the format the Client Connector actually writes: date, time with microseconds, timezone offset, process and thread id, then one of four tokens — ERR, WAR, INF or DBG — and the message. There is no "INFO", "ERROR" or "WARN" in these logs; searching for those finds nothing.

Case 1: the policy never arrives

Symptom. A device behaves as if it held old settings: the wrong forwarding profile, missing exceptions, a switch nobody sets that way any more.

File. ZSAUpm, written by the policy downloader (ZPD).

2025-10-29 08:56:25.771190(+0100)[20002:30012] ERR ZPD: Failed to download UPM policy.

Finding. The analysis records a failed policy download at high severity. The client's settings come from exactly this download. If it fails, the device carries on with the last state it knows, and tells nobody.

Another explanation. A single failed attempt during a network change is normal. What matters is whether a later attempt succeeds. In the same bundle the ZIA state is back at TUNNEL_FORWARDING just under three minutes later: then it was an episode. If the error persists across several cycles, it was not.

Next step. Note the time window and check whether ADAPTER_DOWN_ERROR or SERVER_DOWN_ERROR appear in it too. If the error repeats without those companion states, the case belongs with Zscaler support: with the time window, not the whole bundle.

Case 2: the system proxy points somewhere else

Symptom. Individual destinations bypass the tunnel or land on a foreign proxy. The user reports "it does not work", yet the tunnel is up.

File. ZSAService.

2025-09-04 16:32:21.784349(+0200)[20005:30041] INF PAC URL should be: http://127.0.0.1:9000/systemproxy-1a2b3c4d.pac but its changed to: http://proxy.contoso.example:8080/corp.pac

Finding. The PAC URL was overridden from outside, high severity. The client expects its own locally served PAC file; the system holds a different one. Worth noting: the token is INF, not ERR. The finding rests on what the line says, not on its severity, which is why filtering for errors alone misses it.

Another explanation. A PAC file that parses cleanly is not automatically the right one. The same bundle contains Pac parse success! — a success message, not an acquittal. A group policy object or a second security product may also set the system proxy legitimately.

Next step. Check the PAC file that is actually configured against two addresses: one meant to go direct, one meant to run through the tunnel. That works without a tenant in the free PAC Tester. If the result differs from the intent, the file is the problem, not the client.

Case 3: the tunnel drops, and the cause sits just above it

Symptom. Connections disappear for minutes, then everything is back. The user reports "Zscaler was gone".

File. ZSAUpm.

2025-10-29 08:56:02.110477(+0100)[20002:30012] ERR ZUIfaceChangeMonitor::getAdapterDetails: Failed to get interface info

Finding. Network adapter unavailable, high severity. The line sits half a second after the state change ZIA: TUNNEL_FORWARDING → ADAPTER_DOWN_ERROR. The tunnel did not drop because Zscaler was down, but because the device had no usable network adapter for a moment.

Another explanation. Not every line that looks like a network problem is one. checkTunTcpEchoServerUpImpl and isUdpEchoServerUpImpl are the product's own reachability probe, and Sending NXDOMAIN … name: wpad. is deliberate WPAD suppression. Both belong to normal operation.

Next step. Read the state sequence in the same time window. If it runs through ADAPTER_DOWN_ERROR and ends back at TUNNEL_FORWARDING, it was a local network change: Wi-Fi, VPN, docking station. If FIREWALL_BLOCK_ERROR or SERVER_DOWN_ERROR appear, the case leaves the endpoint.

With CentaurNexusAgent, export and upload disappear, it works from the same rule base as the analysis here. To follow this without a tenant: the free Log Analyzer ships with the very bundle these three lines come from.

Path 2: with CentaurNexusAgent, export and upload disappear

On devices running CentaurNexusAgent, the same process works without user action. CentaurNexusAgent evaluates the ZCC logs directly on the device and transmits structured findings only. No export, no ZIP, no upload, no waiting in the ticket. Our roughly two-and-a-half-minute video on this path shows how a finding like this opens directly inside the support context.

When an authorized operator opens the affected user in the Unified Support Center, the client log findings appear inline, in the same findings view as in the upload path. Each finding carries its time window plus first and last occurrence; even a disruption that happened hours ago remains traceable without the user having to reproduce it. One click opens the same findings in the full Log Analyzer view.

Privacy in both workflows

The upload path is also designed for data economy: logs are analyzed in memory only and are not stored. Personal data in sample lines is obfuscated according to the tenant setting, and every retrieval is audited.

Access to findings is role-gated. It is granted only to those allowed to use Log Analyzer or a support center, and an administrator scoped to domains sees only users of their own domains. Log analysis thus remains a controlled workflow and does not become a side entrance to broad inspection rights.

Zscaler remains the core provider

The Zscaler Client Connector remains the authoritative client software and the source of the log data. CentaurNexus adds evaluation, classification and fix recommendations to the supported workflow in a shared work context for help desk and administration. The findings deliberately point back to the Zscaler side of the problem, such as posture profiles, PAC files or the tunnel configuration, so the correction happens where it belongs.