# SSL / TLS errors

helodata is a **forwarding** proxy — for HTTPS targets, the gateway tunnels a TCP connection via `CONNECT`, and your client negotiates TLS end-to-end with the target. So SSL errors are almost always one of:

1. Your client's CA bundle is stale
2. The target site has a broken TLS config
3. You're trying to intercept TLS yourself with another MITM tool in the chain

## Symptom: `SSL: CERTIFICATE_VERIFY_FAILED` (Python)

```
requests.exceptions.SSLError: HTTPSConnectionPool(host='example.com', port=443):
  Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(...)))
```

**Diagnose**

```bash
# Bypass helodata to isolate the target
openssl s_client -connect example.com:443 -servername example.com < /dev/null

# Then with helodata
curl -v --proxy http://USER:PASS@gate.helodata.io:7777 https://example.com
```

If both fail with the same cert error, **the target itself is misconfigured**.

**Fix options**

* **Update certifi** (Python): `pip install -U certifi`
* **Update CA bundle** (system): `apt update && apt install ca-certificates -y && update-ca-certificates`
* **Disable verification** as last resort — only on a test target:

  ```python
  requests.get(url, verify=False)
  ```

## Symptom: gateway returns `502` + `upstream-tls-error`

```
HTTP/1.1 502
X-Helodata-Error-Code: upstream-tls-error
```

The target's TLS handshake failed against the helodata exit IP. Most often the target:

* Has an expired certificate
* Doesn't include the intermediate certificate in its chain
* Requires a specific TLS version or cipher your exit IP's TLS stack negotiates differently from your local one

The exit IP doesn't actually matter for TLS terms — TLS is end-to-end. The gateway just observed that the handshake didn't complete in the configured time and reported it back.

**Fix**

* Retry with a fresh exit IP (rotate the session)
* If consistent across IPs, the target is broken — confirm with `openssl s_client`

## Symptom: HTTPS works at home, fails via proxy

Most common cause: **DNS resolution**. The local resolver returned an IP for a CDN closest to your home, but the proxy's resolution returned a different (sometimes misconfigured) edge.

**Fix**

* Switch to SOCKS5 with `socks5h://` so the proxy resolves DNS uniformly across your fleet.
* For very few targets, hard-code a known-good DNS over HTTPS (DoH) — but this defeats geo-targeting.

## Symptom: header `X-Helodata-Bypass-TLS-Validation: skipped`

helodata never modifies upstream TLS. If you see hints of certificate mangling in your client's logs, look for **another** MITM proxy in the chain — your corporate firewall, a debug tool like Charles or mitmproxy you forgot to disable, or a VPN client that re-signs certs.

## Self-signed targets

helodata cannot help — it doesn't re-issue certs. Your client must trust the self-signed root explicitly (`requests.get(..., verify="my-ca.pem")`).

## Quick checklist

* [ ] Did this work directly (no proxy) just now?
* [ ] Is `certifi` (Python) or your OS CA bundle up to date?
* [ ] Does `openssl s_client` succeed?
* [ ] Is there another MITM proxy (Charles, mitmproxy, corp firewall) in the chain?
* [ ] Does retrying with a different exit IP help?

If you've answered yes to "still failing" after all of these, open a ticket with `X-Helodata-Request-Id` and the `openssl s_client` output.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/troubleshooting/ssl-errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.