Proxy error reference · Browser and client errors

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

Q: 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.

Q: 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.

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

Last updated: October 13, 2026 · 4 min read

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

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?

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

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

# 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:[email protected]: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.
502 or 504: retry on a new exit. See 502 and 504.
Unwanted environment proxy: set session.trust_env = False in requests, or clean the variables.

Python: build the proxy URL with encoded credentials

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 · 407 · Python guide.

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

HTTP status codes

Browser and client errors

Connection and TLS errors

Residential proxies with docs that cover the failure cases

CrawlRelay residential proxies from $0.50/GB, traffic that never expires.

See pricing Quick start