A Python requests ProxyError is raised when requests (through urllib3) can't use the proxy you configured: it couldn't connect to it, the proxy refused the tunnel, or the proxy closed the connection. The message is long and nested, like ProxyError: HTTPSConnectionPool(host='example.com', port=443): Max retries exceeded with url: / (Caused by ProxyError('Unable to connect to proxy', OSError('Tunnel connection failed: 407 Proxy Authentication Required'))). The useful part is the innermost cause at the end. This guide maps each variant to its fix.
A Minimal Correct Setup
Start from a setup that's known to work, then compare your code against it:
import requests
PROXY = "http://USERNAME:[email protected]:8080"
proxies = {"http": PROXY, "https": PROXY}
r = requests.get("https://api.ipify.org", proxies=proxies, timeout=(10, 30))
print(r.status_code, r.text)Two things in that snippet prevent most ProxyErrors: both "http" and "https" keys are set, and the proxy URL scheme is http:// even for https:// targets.
Variant 1: Tunnel connection failed: 407 Proxy Authentication Required
The proxy rejected your credentials. On NodeProxies that means the username or password is wrong or the plan isn't active. Check for:
- Special characters in the password that aren't URL-encoded. Use urllib.parse.quote(password, safe="") when building the URL.
- Targeting options in the password instead of the username.
- A stale password after you regenerated credentials.
from urllib.parse import quote
user = "USERNAME-country-us"
password = "p@ss:w#rd" # example with special characters
PROXY = f"http://{quote(user, safe='')}:{quote(password, safe='')}@global.nodeproxies.xyz:8080"Full checklist: how to fix proxy error 407.
Variant 2: Tunnel connection failed: 402
The credentials are fine and the plan has run out of bandwidth. Top up in the dashboard; the same credentials start working again.
Variant 3: Tunnel connection failed: 502 / 503
Authentication passed but the proxy couldn't open the tunnel to the target through the chosen exit. Usually transient: retry with a new IP. If it persists for one site only, check whether that site is reachable. See proxy error 502 Bad Gateway.
Variant 4: Cannot connect to proxy / NewConnectionError
requests couldn't open a TCP connection to the proxy. Inner causes and fixes:
- [Errno 111] Connection refused or [Errno 61]: wrong port, or nothing listening there. Use 8080 for HTTP and 1080 for SOCKS5.
- [Errno -2] Name or service not known / nodename nor servname provided: the proxy hostname is misspelled or your DNS can't resolve it.
- Timed out: a firewall is blocking the port. Test with nc -vz global.nodeproxies.xyz 8080.
Variant 5: RemoteDisconnected or Connection aborted
The proxy accepted the TCP connection and closed it without a valid HTTP reply. The usual cause is a protocol mismatch: an http:// proxy URL pointing at the SOCKS5 port 1080. If you want SOCKS5, install the extra with pip install "requests[socks]" and use socks5h://USERNAME:[email protected]:1080.
Variant 6: SSLError wrapped in ProxyError
If the inner error mentions WRONG_VERSION_NUMBER, your proxy URL starts with https://. Change it to http://. Details in SSL errors through a proxy.
Variant 7: ProxyError on Only Some Requests
If most requests succeed and a few raise ProxyError with a 502, 503 or a closed connection, nothing is misconfigured. Individual residential exits occasionally fail, and the fix is a retry with a fresh IP. Catch requests.exceptions.ProxyError separately from other errors, retry it two or three times with a short backoff, and log the root cause (see below) so a sudden jump in failures stands out. A rising rate of 407s mid-run, by contrast, usually means the plan stopped being active, so check the dashboard rather than retrying.
The Hidden Cause: Environment Variables
requests reads HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY from the environment by default (trust_env=True). A stale proxy in your shell profile or a corporate environment can override or conflict with what you think you configured. Check what requests will actually use:
import os
import requests
from requests.utils import get_environ_proxies
print({k: v for k, v in os.environ.items() if "proxy" in k.lower()})
print(get_environ_proxies("https://example.com"))
# To ignore environment proxies completely:
s = requests.Session()
s.trust_env = False
s.proxies = {
"http": "http://USERNAME:[email protected]:8080",
"https": "http://USERNAME:[email protected]:8080",
}
print(s.get("https://api.ipify.org", timeout=30).text)Also check NO_PROXY: if the target host matches an entry there, requests goes direct and you'll wonder why your IP didn't change.
Print the Root Cause Automatically
Rather than reading the nested message by eye, walk the exception chain:
import requests
def root_cause(exc):
seen = set()
while id(exc) not in seen:
seen.add(id(exc))
nxt = (getattr(exc, "reason", None) or exc.__cause__
or next((a for a in exc.args if isinstance(a, BaseException)), None))
if not isinstance(nxt, BaseException):
return exc
exc = nxt
return exc
try:
requests.get("https://example.com", proxies={"https": "http://USERNAME:[email protected]:8080"}, timeout=20)
except requests.exceptions.ProxyError as e:
print("root cause:", repr(root_cause(e)))Getting requests Working with NodeProxies
Use http://USERNAME:[email protected]:8080 for both keys, add options like -country-us to the username, and set a timeout. Scraping in Python? Our web scraping with proxies guide builds on this. Create an account to get credentials.
FAQ
What does "Unable to connect to proxy" mean in requests?
requests reached a point where the proxy couldn't be used. Read the inner error: a 407 means credentials, a 402 means bandwidth, a 502/503 means the target or upstream, and connection errors mean host, port or firewall.
Why does requests ignore my proxy for HTTPS URLs?
You probably only set the "http" key. Add an "https" key with the same http:// proxy URL.
Do I need requests[socks] for SOCKS5 proxies?
Yes. Install it with pip install "requests[socks]" and use a socks5h:// URL on port 1080.
