> For the complete documentation index, see [llms.txt](https://docs.ipdunar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipdunar.com/troubleshooting/ssl-errors.md).

# SSL / TLS errors

ipdunar 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 ipdunar to isolate the target
openssl s_client -connect example.com:443 -servername example.com < /dev/null

# Then with ipdunar
curl -v --proxy http://USER:PASS@gate.ipdunar.com: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-IPdunar-Error-Code: upstream-tls-error
```

The target's TLS handshake failed against the ipdunar 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-IPdunar-Bypass-TLS-Validation: skipped`

ipdunar 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

ipdunar 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-IPdunar-Request-Id` and the `openssl s_client` output.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ipdunar.com/troubleshooting/ssl-errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
