Quick answer
What does SOCKS5 proxy errors mean with a proxy?
SOCKS5 errors come in three kinds: your client lacks SOCKS support, the server rejected your username and password, or the server could not reach the target and returned a reply code. With CrawlRelay, install SOCKS support first (for Python requests: requests[socks]), use the SOCKS5 port, and prefer socks5h:// so DNS resolves at the exit, not on your machine.
SOCKS5 proxy errors at a glance
| Error | SOCKS5 proxy errors |
|---|---|
| Type | SOCKS5 protocol or client error |
| Sent by | The SOCKS5 server (reply codes) or your client library (missing support) |
| Defined in | SOCKS5: RFC 1928; username/password authentication: RFC 1929 |
| Retry it? | Depends on the reply code |
| First check | Confirm the client supports SOCKS5 with authentication, then read the reply code |
What does SOCKS5 proxy errors mean?
SOCKS5, defined in RFC 1928, relays TCP connections without reading HTTP. Authentication by username and password is a separate small exchange, defined in RFC 1929. After authentication, the client asks for a connection to a host and port, and the server answers with a one-byte reply code.
Reply 0x00 means success. Codes 0x01 to 0x08 describe failures, from a general server failure to an unsupported address type. Clients translate these codes into messages of their own.
What does a SOCKS5 error 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:
- Python requests without PySocks:
InvalidSchema: Missing dependencies for SOCKS support. - curl, rejected credentials:
curl: (97) User was rejected by the SOCKS5 server - Reply 0x01: 'general SOCKS server failure'
- Reply 0x04 / 0x05: 'Host unreachable' / 'Connection refused' by the target
- Reply 0x08: 'Address type not supported'
What causes a SOCKS5 error?
Most likely first:
- No SOCKS support installed in the client library.
- Wrong credentials or credentials not URL-encoded.
- The HTTP port used for SOCKS, or the SOCKS port used for HTTP.
- A target that refused or was unreachable from the exit.
- Local DNS with
socks5://: the client resolves the hostname itself, which can fail or return the wrong regional address.
How do I diagnose a SOCKS5 error step by step?
- Confirm SOCKS support: in Python,
pip show pysocks; in Node.js, a SOCKS agent package. - Run the curl test below against the SOCKS5 port with
--socks5-hostname. - Read the reply code or message.
- Compare
socks5://andsocks5h://for the same target.
# 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_URLHow do I fix a SOCKS5 error?
- Install support:
pip install "requests[socks]"; in Node.js, use a SOCKS proxy agent. - Use the SOCKS5 port for
socks5h://URLs and the HTTP port forhttp://URLs. - Prefer
socks5h://so the exit resolves DNS, which matches what local visitors get. - For reply 0x04 or 0x05, test the target without the proxy; it may be down or refusing.
- For browsers, use the HTTP port: Chromium does not support SOCKS5 authentication.
import requests
# socks5h:// sends the hostname to the proxy, so DNS resolves at the exit
proxy = "socks5h://USERNAME:[email protected]:7778"
r = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=(10, 30))
print(r.status_code, r.text)Should I retry after a SOCKS5 error?
Retry only failures at the target side, such as host unreachable or connection refused, and only once on a new exit. Authentication failures and missing client support repeat until you fix the configuration.
How does SOCKS5 proxy errors apply to CrawlRelay?
CrawlRelay serves SOCKS5 on its own port, listed below, with the same username format and password as the HTTP port. Targeting and sessions work the same way on both ports.
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: Cannot connect to proxy · curl guide · Python guide.
SOCKS5 proxy errors: questions developers ask
What is the difference between socks5:// and socks5h://?
With socks5:// your client resolves the hostname to an IP address itself and sends the IP to the proxy. With socks5h:// it sends the hostname, and the proxy side resolves it. Use socks5h:// for scraping: DNS then happens at the exit, so you get the same regional answers that local visitors get.
Should I use SOCKS5 or HTTP proxies for scraping?
For web pages, both work, and HTTP proxies are simpler: every HTTP library and browser supports them with authentication. Use SOCKS5 for non-HTTP protocols or for tools that only speak SOCKS. Chromium-based browsers cannot authenticate to SOCKS5, so use the HTTP port there.
Why does curl say 'User was rejected by the SOCKS5 server'?
The SOCKS5 server refused the username and password exchange. Check the credentials, URL-encode special characters, and confirm that you are using the SOCKS5 port. The same username and password must work on the HTTP port if the account is active.
Other proxy errors in this reference
HTTP status codes
- 401 Unauthorized vs 407
- 403 Forbidden
- 407 Proxy Authentication Required
- 429 Too Many Requests
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
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.