> ## 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).

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), make sure Zscaler preserves HTTP/2 for traffic to the custom management-plane hostname.

## 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:**

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), run this check against the custom management-plane hostname. Also check `app.gitpod.io` if users authenticate built-in integrations.

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

If the issuer shows "Zscaler Inc." instead of the expected certificate issuer, SSL inspection is active.

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

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), add the custom management-plane hostname to the SSL inspection bypass list. Browser clients still need access to `app.gitpod.io` to authenticate built-in integrations.

**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 is blocking the Ona management-plane hostname, OAuth callbacks, or runner-gateway protocols.

**Fix:**

* Allow outbound HTTPS (TCP 443) to the runner's configured Ona management-plane hostname (`app.gitpod.io` by default). Allowlist the hostname rather than the IP addresses it currently resolves to.
* Ensure WebSocket and gRPC traffic is allowed
* **Workaround:** Use Personal Access Tokens instead of OAuth while configuring

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), allow outbound HTTPS to the custom management-plane hostname used by the runner, not only `app.gitpod.io`.

## Configuration checklist

Work with your network team to configure:

**SSL inspection:**

* [ ] Add `app.gitpod.io` to the bypass list
* [ ] Verify the certificate shows the expected issuer, not "Zscaler"

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), also add the custom management-plane hostname to the bypass list and verify its certificate issuer.

**HTTP/2:**

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

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), confirm this setting applies to traffic for the custom management-plane hostname.

**Network:**

* [ ] Allow outbound HTTPS (TCP 443) to `app.gitpod.io`
* [ ] Allow WebSocket and gRPC traffic

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), also allow outbound HTTPS, WebSocket, and gRPC traffic to the custom management-plane hostname.

## Verify configuration

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), replace `app.gitpod.io` with the custom management-plane hostname in both commands. Test `app.gitpod.io` separately if users authenticate built-in integrations.

```bash theme={null}
# Check SSL (issuer should not be 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](https://ona.com/docs/ona/reference/cli.md) for details.
* Output from `curl -I -v https://app.gitpod.io`
* [Runner support bundle](https://ona.com/docs/ona/troubleshooting.md#runner-support-bundles)
* [Environment support bundle](https://ona.com/docs/ona/troubleshooting.md#environment-support-bundles), if the environment is reachable
* VS Code / Ona extension logs
* Network configuration details

> [!WARNING]
>
> If your organization uses a [custom domain](https://ona.com/docs/ona/custom-domain.md), include the `curl -I -v` output for the custom management-plane hostname. Include the output for `app.gitpod.io` too if built-in integration authentication is affected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.