Troubleshooting Engine

“Site X does not work for user Y” is the most common ticket a Zscaler team receives and the most tedious to answer, because the answer is spread across forwarding profiles, a dozen policy types on ZIA, the ZPA policies and the logs. The Troubleshooting Engine puts the case in one panel and answers the first question directly: will this traffic get through, and if not, what stops it?

It is for help desk and operations: the people who need a root cause, not a theory.

When to use it

• An access ticket: a user, a location or a device cannot reach a destination.
• A “should this work?” question: before a rollout, check what a group will actually hit.
• A forwarding question: traffic is leaving through the wrong path or the wrong cloud.
• A page that half works: the main site loads, something inside it does not. That is the HAR case.
• A ticket with a time on it: “it failed at about 10:40”. That is the Log Investigation case, one tab away.
• A shift handover: save and name the session and let the next engineer resume exactly where you stopped.

Where to find it in the UI

Hover the ZHERO icon and click the Troubleshooting Engine button (wrench icon). The drawer opens nearly full width.

The drawer has four tabs: Forwarding, Policies, Insights and Investigation. The HAR Analysis panel sits alongside them, collapsed until you need it.

The ? button in the drawer header opens a menu with the manual pages for this drawer (see Contextual help).

Criteria and scenarios

In the left panel, Criteria Selection, you describe the ticket:

• Source Criteria: users, groups, departments, locations, device groups. The “who and from where”.
• Destination Criteria: URLs, URL categories, cloud apps. The “to what”.

ZHERO turns the criteria into scenarios: each combination of a source and a destination is one scenario (who, from where, to what). A counter shows how many scenarios the criteria produce, up to 12. Above that, nothing is analysed: reduce the criteria until the counter is back within the limit.

The scenarios live in the scenario rail, along the side of the Policies, Insights and Investigation tabs. Click a scenario and every tab follows it. Collapsed, the rail becomes a column of badges with the answer for each scenario, so a dozen cases can be read at a glance. Clear All empties the criteria and starts over.

The reachability verdict

At the top of the Policies tab, for the selected scenario, ZHERO asks the question the ticket is really about: will this source reach this destination? The answer comes in two kinds.

A certain answer, when the configuration decides on its own:

Verdict	Meaning
Reachable (ZPA: Allowed)	Every engine on the path lets the traffic through
Blocked by an engine	The engine and the rule that stop it are named, with the rule number
Not through ZPA	The destination is not a ZPA application, so ZPA is not on the path
Route depends	Client forwarding does not settle whether the traffic goes to ZIA or to ZPA: both answers are shown (see below)

An estimate, when the answer depends on something the configuration alone cannot settle (a platform, a device group, a location, a trusted network). The verdict then carries a percentage and one of three readings: Probably reachable, It depends or Probably blocked. A bar shows how much of the traffic is expected to get through and how much to stop.

A condition that only changes whether the traffic is inspected does not turn the verdict into an estimate: ZHERO still says Reachable or Blocked, lists the condition under Open conditions: they do not change whether it gets through, and counts it in the Inspected figure.

Next to the verdict, Where the traffic goes shows the route before any policy applies: Client Connector, the client forwarding rule that decides, and whether the traffic goes out through ZIA or through ZPA. Open the Forwarding tab takes you to the full picture.

The path through the engines

Under the verdict, one tile per engine shows what that engine does to this traffic, in the order the traffic meets them. The first rule that matches wins, as in Zscaler itself.

• ZIA: Firewall, DNS, SSL Inspection, Cloud App Control, URL Filtering.
• ZPA: first the application segment that matches the destination (with notes such as a port that is not included, or a segment set to bypass), then Client Forwarding and Access.

Cloud App Control rules enter the verdict when the URL lookup identifies the app. Zscaler recognises some apps only from the traffic, not from the host name: for those hosts the lookup returns only the URL category, so the verdict cannot say what a cloud app rule will do. The logs can: check them in the Insights tab or with an investigation.

Each tile says in plain words what happened there: allowed by a named rule, allowed by default because no rule matches, skipped because an earlier rule sent the traffic past it, or not reached because the traffic was stopped before. For ZIA the verdict also says whether the traffic is inspected, as a separate figure.

What the answer depends on

When the verdict is an estimate, the block What the answer depends on lists the open conditions and how each one was weighed. On ZIA, ZHERO uses the best evidence available:

1. The user’s own logs, for example “12 of 15 transactions of this user came from” a given location.
2. The tenant’s ZCC fleet, for example the share of enrolled devices that run a given platform.
3. With no data at all, the condition is counted as 50%, and the page says so: Nothing measures it: counted as 50%.

On ZPA the conditions (client types, posture profiles, platforms) are not weighed on logs or on the fleet: each one is counted as 50%, and the page says so in the same words.

Each condition carries a tag with its source, so you know whether a percentage comes from this user, from the fleet, or from nothing at all. How this is worked out shows how the final figure is reached.

When a single user is involved and a condition can be measured in the logs, Look in the web logs fills the Insights tab with the right query. It does not run it: you press Run when you are ready.

Predicted against observed

When web logs for exactly the selected scenario are on screen in Insights, a line compares the two: what the verdict predicted and what the logs show (how many transactions passed, how many were blocked). If they disagree, ZHERO names the engine and the rule where they part ways. A disagreement usually means one of three things: a condition was read differently from how the traffic really arrived, a rule changed since, or the traffic took another path. Blocks that come from content checks (a file, a threat, a DLP match) are reported separately, because no configuration verdict can predict them.

ZIA and ZPA side by side

On a tenant with both products, the Policies tab shows the ZPA answer next to the ZIA one, for the same scenario. On a ZPA-only tenant the ZPA verdict takes the top of the tab and users are picked from the ZPA directory. When a destination is not defined as a private application, ZHERO says that the traffic is likely not going through ZPA rather than leaving the section empty. The same goes the other way: when client forwarding sends a destination to ZPA, the ZIA card says the traffic is likely not traversing ZIA, and still tells you what ZIA would do if it did.

When client forwarding does not settle the route for a scenario (a forwarding rule applies only to some client types, for example), the rail shows Route depends and the Policies tab puts the two answers next to each other, Through ZIA and Through ZPA, each with its own tiles and rules.

Step by step

1. Build the criteria and check the scenario counter.

2. Pick a scenario in the rail and read the verdict at the top of the Policies tab.

3. Read the rule list under the verdict. For the selected scenario ZHERO lists the matching rules per policy type, with the action and the rule order. On ZIA eleven policy types are covered:

   Firewall rules	DNS rules	IPS rules
   Forwarding rules	SSL Inspection	URL Filtering
   Cloud App rules	File Type rules	DLP rules
   Sandbox rules	Bandwidth rules

   On ZPA: Client Forwarding, Access and Timeout policies, plus AppProtection and Isolation where the tenant has rules of that type.

   Rules that match but are switched off are shown in their own group instead of being silently skipped: they do nothing to this traffic until someone enables them, which is often the answer on its own. So are rules that are unreachable for these criteria: the rule everybody assumed was doing the work never runs.

4. Read the Forwarding tab. The traffic flow is drawn as a Sankey diagram running from platforms (device groups) through forwarding profiles and network states (trusted, off trusted, VPN) to app profiles, and out to ZIA or DIRECT. The ZPA branch leaves straight from the network state, and appears only where the forwarding profile actually carries a ZPA action for it. When all network states of a profile behave the same, the diagram skips that layer and links the profile straight to its app profiles (and to ZPA). A misassigned forwarding profile is visible as a path going somewhere you did not expect. The diagram shows how your configuration routes the traffic, not measured volumes: hover an app profile to see what shapes its ZIA and DIRECT split.

   

   

5. Read the Insights tab. This queries the real logs for the selected scenario, in three sub-tabs: ZIA Web, ZIA Firewall and, where ZPA diagnostics are enabled, ZPA Diagnostics. Configuration says what should happen; Insights says what did. Each scenario card in the rail also has a shortcut to its logs. Open in panel moves the query and its results into a floating Logs panel and closes the drawer, so you can keep them on screen while you work in the console.

6. If the ticket has a time on it, open Investigation. The Log Investigation runs the relevant log reads for the selected user and destination and returns one timeline with diagnosis cards.

7. If a page half works, add a HAR (see HAR analysis below).

8. Save the session. Save or Save New, then give it a name with the pencil icon. Reload it later from the session cards in the bottom bar.

HAR analysis

Drag a HAR file into the HAR Analysis panel. ZHERO reads it in the browser, extracts the domains, groups the errors, and lets you select the domains that matter so the rest of the analysis narrows to them. For each request it shows:

• The protocol (HTTP/1.1, HTTP/2, HTTP/3). HTTP/3 is highlighted with a warning: it runs over QUIC (UDP 443), which ZIA does not inspect, so those requests probably did not go through ZIA. Blocking QUIC in the firewall makes the browser fall back to HTTP/2 over TCP.
• Errors explained in plain words, grouped by kind: client errors (4xx), server errors (5xx), certificate problems, timeouts, failed connections, proxy forwarding and proxy authentication failures, DNS resolution failures. Browser network error codes get a sentence that says what actually went wrong.
• Requests handled by Zscaler, marked ZS: redirects to Zscaler authentication and responses that came from Zscaler itself, such as a block or caution page. A Zscaler response with a 403 is counted as Blocked by Zscaler.

Requests blocked by another browser extension or cancelled by the page are counted apart and are no longer treated as errors, so they do not send you chasing a problem that is not there.

Investigate this request, the search icon on a failed or Zscaler-handled request, opens the Investigation tab with that host and the exact time of the request already filled in. It does not run anything: you check the form and press Run.

Sessions and names

A session keeps the criteria, the scenarios and the state of the tabs. Save it with Save or Save New, and give it a name of your own with the pencil icon (up to 80 characters; an empty name goes back to the automatic one).

Named sessions are never cleaned up automatically. Unnamed sessions are kept for 7 days, and only the latest 10. If a session matters, name it.

What to watch

• An estimate is not a verdict. “Probably reachable” at 85% means some traffic in this scenario will be stopped. Read what the answer depends on before closing the ticket.
• Where the evidence comes from. A percentage from the user’s own logs describes this user; a percentage from the fleet describes the tenant. The tag on each condition tells you which.
• The order of the matching rules. The first match wins, so a permissive rule above a specific one explains a lot of “but we have a rule for that”.
• The gap between prediction and logs. Configuration allows it, logs show it blocked: follow the engine and the rule the comparison names, then look outside the policy set, starting with the forwarding path.
• HTTP/3 in a HAR. Requests over QUIC may be bypassing ZIA entirely, which explains a lot of “it works on one browser and not on another”.
• Third-party calls in a HAR. A page that “does not work” is frequently three background API calls to a domain nobody thought to allow.

Limits and notes

• Up to 12 scenarios per analysis. Past that, nothing is analysed until you reduce the criteria.
• The verdict reads the configuration. It does not predict blocks that depend on content (a file, a threat signature, a DLP match). IPS rules appear in the rule list but not on the verdict path, because an IPS rule acts only on traffic that matches a threat signature.
• HAR analysis happens entirely in your browser. The file is parsed locally and never uploaded, and query strings are removed when the file is read, so they are never stored. A HAR can still contain sensitive data, including cookies and headers: handle the file itself with the same care you would give a credential.
• Sessions are stored locally in your browser. They survive a reload; they do not follow you to another machine.
• Insights needs the log query to be available to your admin role. Where it is not, the configuration tabs still work. The ZPA Diagnostics sub-tab needs ZPA diagnostics to be enabled for your tenant.
• Nothing queries the logs by itself. Zscaler allows one log query at a time per admin session, so ZHERO pre-fills and waits for you to press Run instead of replacing a query you already have running.
• The engine needs the full licence. On a trial the wrench button opens a premium-feature panel instead of the drawer, naming what the engine does rather than failing silently.

FAQ

Does anything I analyse here leave my browser? The HAR parsing, the verdict and the policy matching run locally. The Insights and Investigation tabs query Zscaler’s own logs through your authenticated session, exactly as the console would.

The verdict says Reachable but the user is blocked. Check the Insights tab for the same scenario: the comparison line names the engine where logs and configuration disagree. The most common causes are a condition that does not hold for this user (another location, another platform), a recent rule change, or a block on content, which the verdict does not predict.

Why “It depends” and not a yes or no? Because the configuration does not decide on its own: a rule applies only on some platforms, some locations or some device groups. The percentage is the share of traffic expected to get through, weighed on the best evidence available, and the page shows which evidence it used.

How do I capture a HAR file? In the browser, open the developer tools on the Network tab, reproduce the problem, then export the requests as a HAR. Capture only the reproduction: a HAR of a long session is both harder to read and more sensitive.

Can I share a session with a colleague? Sessions are local to your browser. For a handover in the same team, the practical route is a to-do with the findings in a comment, linked to the entities involved.

Why is the Forwarding tab empty? The criteria selected do not resolve to a forwarding path, usually because no device or location criterion is set. Add one.

Related pages

• Log Investigation: from “it failed at about 10:40” to a timeline with the cause
• Floating Logs Panel: the logs of any entity, over the console
• ZPA Diagnostics Engine: who and what is behind a ZPA filter
• Unreachable Policy Detection: why a rule never runs
• Traffic Analytics: volumes per rule, category and location
• Getting Around ZHERO

Next steps

1. Take your next access ticket and rebuild it as criteria instead of guessing
2. Read the verdict, then compare it with the Insights tab before you change anything
3. If the ticket has a time, run the Investigation for that moment
4. Ask the reporter for a HAR the next time a page only half works
5. Name the session before your shift ends