# ProxyError: 'Unable to connect to proxy' in Python and Node.js

> requests.exceptions.ProxyError 'Unable to connect to proxy' explained: read the nested cause (refused, timeout, DNS, 407, 502) and apply the right fix.

- URL: https://crawlrelay.com/docs/errors/cannot-connect-to-proxy/
- Last updated: 2026-10-13
- Publisher: CrawlRelay (https://crawlrelay.com)

Client library error (Python, Node.js): the exact message in each tool, the likely causes in order, and the fix that works.

**Quick answer — What does Cannot connect to proxy (ProxyError) mean with a proxy?**

**'Unable to connect to proxy'** is a wrapper error: Python's requests and urllib3 put the real reason inside it. Read the innermost cause. 'Connection refused' or a timeout means a host, port or network problem; 'Failed to resolve' means DNS; 'Tunnel connection failed: 407' means credentials. With CrawlRelay, each of these has a one-line fix.

## Cannot connect to proxy (ProxyError) at a glance

| Attribute | Value |
| --- | --- |
| Error | Cannot connect to proxy (ProxyError) |
| Type | Client library error (Python, Node.js) |
| Sent by | Your HTTP client, before or while talking to the proxy |
| Defined in | Library error; read the nested cause for the real reason |
| Retry it? | Depends on the nested cause |
| First check | Read the innermost exception: refused, timed out, name resolution, or a status code |

## What does Cannot connect to proxy (ProxyError) mean?

urllib3 raises one `ProxyError` for every failure that involves the proxy, and requests passes it on. The useful information sits in the nested exception, which the traceback prints at the end of a long line.

Node.js clients behave differently: they report the socket error directly, such as `ECONNREFUSED` or `ETIMEDOUT`, often without saying that the address was the proxy's.

## What does 'Cannot connect to proxy' look like in Python, curl, Node.js and browsers?

The same failure prints differently in every tool. These are the messages to search your logs for:

- **Refused:** `ProxyError('Unable to connect to proxy', NewConnectionError(... Connection refused))`
- **DNS:** `NameResolutionError(... Failed to resolve ...)` inside the `ProxyError`
- **Credentials:** `OSError('Tunnel connection failed: 407 Proxy Authentication Required')`
- **Gateway error:** `OSError('Tunnel connection failed: 502 Bad Gateway')`
- **Node.js:** `Error: connect ECONNREFUSED`, `ETIMEDOUT` or `ENOTFOUND`, followed by the proxy's address

## What causes 'Cannot connect to proxy'?

Most likely first:

- **Wrong host or port** in the proxy URL.
- **A missing scheme**: `host:port` without `http://` is parsed in surprising ways by some libraries.
- **Blocked outbound traffic** on your network or server.
- **Credentials or gateway errors** that surface during the CONNECT step, wrapped in the same exception.
- **Environment variables** such as `HTTPS_PROXY` that point to an old proxy and override your code.

## How do I diagnose 'Cannot connect to proxy' step by step?

1. Print the full exception and read the last nested cause.
2. Print `requests.utils.get_environ_proxies(url)` or the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` variables to see what else is configured.
3. Run the curl test below from the same machine.
4. Match the cause to the fix list below.

*Test the failing URL with curl (HTTP port, verbose)*

```bash
# Use the URL that fails; with https://api.ipify.org instead, you test the gateway alone.
# "HTTP/1.1 200 Connection established" first, then the site's own status: the site answered.
curl -v -x http://USERNAME:PASSWORD@gw.crawlrelay.com:7777 https://TARGET_URL

# Same test through the SOCKS5 port, with DNS resolved at the exit
curl -v --socks5-hostname gw.crawlrelay.com:7778 --proxy-user USERNAME:PASSWORD https://TARGET_URL
```

## How do I fix 'Cannot connect to proxy'?

- **Refused or timed out:** fix the host and port, or open outbound traffic to the gateway.
- **Failed to resolve:** check DNS on the machine; try the host with `nslookup`.
- **407:** fix and URL-encode the credentials. See [407 Proxy Authentication Required](https://crawlrelay.com/docs/errors/407-proxy-authentication-required/).
- **502 or 504:** retry on a new exit. See [502](https://crawlrelay.com/docs/errors/502-bad-gateway/) and [504](https://crawlrelay.com/docs/errors/504-gateway-timeout/).
- **Unwanted environment proxy:** set `session.trust_env = False` in requests, or clean the variables.

*Python: build the proxy URL with encoded credentials*

```python
from urllib.parse import quote

import requests

user = "USERNAME-country-us"
password = "p@ss:word/1"  # example containing special characters

# safe="" also encodes "/", "@" and ":" inside the credentials
proxy = "http://{}:{}@gw.crawlrelay.com:7777".format(
    quote(user, safe=""), quote(password, safe="")
)
proxies = {"http": proxy, "https": proxy}  # http:// for both keys

r = requests.get("https://api.ipify.org", proxies=proxies, timeout=(10, 30))
print(r.status_code, r.text)
```

## Should I retry after 'Cannot connect to proxy'?

Retry only the network-level causes that can change: timeouts and gateway errors such as 502 or 504. A refused connection, a DNS failure or a 407 will repeat until you change the configuration, so make them fatal in your error handling.

## How does Cannot connect to proxy (ProxyError) apply to CrawlRelay?

For CrawlRelay, the proxy URL is `http://USERNAME:PASSWORD@` followed by the gateway host and HTTP port listed below, for HTTP and HTTPS targets alike. Use the same `http://` URL for both the `http` and `https` keys in requests: the scheme names the protocol spoken to the proxy, not to the website.

Gateway: `gw.crawlrelay.com`, port 7777 (HTTP, HTTPS through CONNECT) and port 7778 (SOCKS5). Username format: `USERNAME-country-{cc}-state-{state}-city-{city}-zip-{zip}-asn-{asn}-session-{id}-ttl-{minutes}`. Related: [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/docs/errors/ssl-wrong-version-number/) · [407](https://crawlrelay.com/docs/errors/407-proxy-authentication-required/) · [Python guide](https://crawlrelay.com/docs/python/).

## Cannot connect to proxy (ProxyError): questions developers ask

### What does 'Max retries exceeded with url' mean with a proxy?

It means urllib3 gave up after its retry budget, and the real reason follows in the 'Caused by' part of the message. With a proxy, that part is usually a ProxyError with a nested cause: connection refused, a timeout, a name-resolution failure or a tunnel status such as 407.

### Why does requests use a proxy I did not configure?

requests reads the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables by default, and on Windows it also reads system proxy settings. A leftover value then overrides your expectations. Set `session.trust_env = False`, or pass the proxies explicitly on every request.

### Do I write http:// or https:// in front of the proxy address?

Write `http://` for an HTTP proxy, even when the website uses HTTPS. The scheme describes how your client talks to the proxy. Writing `https://` makes newer urllib3 versions start TLS with the proxy, which fails on a plain HTTP proxy port with an SSL error.

## Other proxy errors in this reference

- [401 Unauthorized vs 407](https://crawlrelay.com/docs/errors/401-unauthorized/)
- [403 Forbidden](https://crawlrelay.com/docs/errors/403-forbidden/)
- [407 Proxy Authentication Required](https://crawlrelay.com/docs/errors/407-proxy-authentication-required/)
- [429 Too Many Requests](https://crawlrelay.com/docs/errors/429-too-many-requests/)
- [502 Bad Gateway](https://crawlrelay.com/docs/errors/502-bad-gateway/)
- [503 Service Unavailable](https://crawlrelay.com/docs/errors/503-service-unavailable/)
- [504 Gateway Timeout](https://crawlrelay.com/docs/errors/504-gateway-timeout/)
- [Cannot connect to proxy (ProxyError)](https://crawlrelay.com/docs/errors/cannot-connect-to-proxy/)
- [Connection reset by peer (ECONNRESET)](https://crawlrelay.com/docs/errors/connection-reset/)
- [ERR_PROXY_CONNECTION_FAILED](https://crawlrelay.com/docs/errors/err-proxy-connection-failed/)
- [ERR_TUNNEL_CONNECTION_FAILED](https://crawlrelay.com/docs/errors/err-tunnel-connection-failed/)
- [Read timed out (ReadTimeout)](https://crawlrelay.com/docs/errors/read-timeout/)
- [SOCKS5 proxy errors](https://crawlrelay.com/docs/errors/socks5-proxy-errors/)
- [SSL: CERTIFICATE_VERIFY_FAILED](https://crawlrelay.com/docs/errors/ssl-certificate-verify-failed/)
- [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/docs/errors/ssl-wrong-version-number/)

**Residential proxies with docs that cover the failure cases** CrawlRelay residential proxies from $0.50/GB, traffic that never expires. [See pricing](https://crawlrelay.com/pricing/) · [Quick start](https://crawlrelay.com/docs/)

---

CrawlRelay: CrawlRelay is a developer-first rotating residential and 4G/5G mobile proxy service for scrapers and AI data pipelines: non-expiring pay-as-you-go traffic from $0.50/GB, paid in crypto, with no ID upload. No KYC — no ID, no selfie, no documents. Pay in crypto.