> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zscaler troubleshooting

> Troubleshoot Zscaler compatibility issues with Ona

## HTTP/2 protocol downgrade

**Symptoms:** CLI failures, connection timeouts, protocol errors

**Cause:** Zscaler downgrades HTTP/2 to HTTP/1.1 for SSL-inspected traffic.

**Fix:** Contact your Zscaler admin to enable HTTP/2 for SSL-inspected traffic under `Administration > Advanced Settings`. See [Zscaler docs](https://www.zscaler.com/de/blogs/product-insights/http-2-better-faster-stronger).

## SSL certificate verification failures

**Symptoms:** VS Code can't connect, "certificate verify failed", untrusted certificate warnings

**Cause:** Zscaler intercepts HTTPS and presents its own certificates. Apps with custom cert stores may not trust them.

**Check if Zscaler is intercepting:**

```bash theme={null}
curl -I -v https://app.gitpod.io
# Windows: curl.exe -I -v -w '\n%{certs}\n' https://app.gitpod.io
```

If issuer shows "Zscaler Inc." instead of "Amazon", SSL inspection is active.

**Fix (recommended):** Add `app.gitpod.io` to SSL inspection bypass list.

**Alternative for VS Code:** Enable "System certificates" in VS Code settings (requires v1.97+). If issues persist, also enable "Electron Fetch" and "System Certificates V2".

## Runner connection issues

**Symptoms:** Runner can't connect, OAuth failures, "connection refused" errors

**Cause:** Zscaler blocking IP ranges, OAuth callbacks, or runner-gateway protocols.

**Fix:**

* Whitelist Ona's static IP ranges (see [access requirements](/ona/runners/aws/detailed-access-requirements))
* Ensure WebSocket and gRPC traffic is allowed
* **Workaround:** Use Personal Access Tokens instead of OAuth while configuring

## Configuration checklist

Work with your network team to configure:

**SSL inspection:**

* [ ] Add `app.gitpod.io` to bypass list
* [ ] Verify cert issuer shows "Amazon" not "Zscaler"

**HTTP/2:**

* [ ] Enable HTTP/2 for SSL-inspected traffic in Advanced Settings

**Network:**

* [ ] Whitelist Ona IP ranges
* [ ] Allow WebSocket and gRPC traffic

## Verify configuration

```bash theme={null}
# Check SSL (issuer should be Amazon, not Zscaler)
curl -I -v https://app.gitpod.io

# Check HTTP/2
curl --http2 -I https://app.gitpod.io
```

Then test VS Code extension and runner connectivity.

## Getting help

Collect and share with support:

* Output of `ona network-troubleshoot`, run from the machine where the connection to Ona is failing. This tests DNS, TCP, TLS, and authenticated API connectivity. See the [CLI reference](/ona/reference/cli) for details.
* Output from `curl -I -v https://app.gitpod.io`
* [Runner support bundle](/ona/troubleshooting#runner-support-bundles)
* [Environment support bundle](/ona/troubleshooting#environment-support-bundles), if the environment is reachable
* VS Code / Ona extension logs
* Network configuration details