SOCKS5 is unusual among proxy protocols in that it tells you exactly why it failed. The protocol, defined in RFC 1928, gives the proxy a one-byte reply field for every connection request, and the values are fixed: 0 for success, then 1 through 8 for eight distinct kinds of failure. Every SOCKS5 client, from curl to Chrome to a Python library, receives that byte and turns it into words, and most of the words people search for ("general SOCKS server failure", "connection not allowed by ruleset", "host unreachable") are the RFC's own names for those values.
That makes SOCKS5 errors more diagnosable than HTTP proxy errors, provided you know what the numbers mean and which of them your client is showing you. This guide walks the handshake, decodes each reply, covers the authentication failures that happen before any reply is sent, and lists the wording each common client uses so you can map it back.
How a SOCKS5 connection is negotiated
Three exchanges happen before any data flows, and each can fail in its own way.
- Method negotiation. The client lists the authentication methods it supports (no authentication, username and password, GSSAPI). The proxy picks one, or answers
0xFF, no acceptable methods. - Authentication. If the proxy chose username and password, the client sends them (RFC 1929) and the proxy answers with a status byte: 0 for success, anything else for failure, after which the connection closes.
- The request. The client asks for a command, almost always CONNECT to a destination given as an IPv4 address, an IPv6 address, or a hostname. The proxy answers with the reply byte, and on 0 the tunnel is open.
Failures in the third step carry the numbered replies. Failures in the first two are authentication errors, and failures before the first step, where the proxy is not a SOCKS proxy at all, produce protocol garbage that clients report in their own words.
The reply codes
| Reply | RFC 1928 name | What the proxy is saying | Usual cause | Fix |
|---|---|---|---|---|
| 0 | succeeded | Tunnel open | ||
| 1 | general SOCKS server failure | Could not complete the request, unclassified | Onward connection failed, overload, broken upstream | Try another target; if all fail, change proxy |
| 2 | connection not allowed by ruleset | A rule forbids this request | Port or destination denied, source not permitted for it | Change port or target, or proxy |
| 3 | Network unreachable | The proxy has no route to that network | Destination network down or filtered from the proxy | Another exit |
| 4 | Host unreachable | The proxy cannot reach the host | Unresolvable name, host down, or blocked from the proxy | Resolve on the proxy side; another exit |
| 5 | Connection refused | The destination refused the proxy | Nothing listening on that port at the target | Check the port; the target, not the proxy |
| 6 | TTL expired | The connection attempt timed out on the proxy side | Slow or filtered path from the proxy | Another exit, or longer timeouts |
| 7 | Command not supported | The proxy does not do this command | UDP ASSOCIATE or BIND on a CONNECT-only proxy | A proxy that supports the command |
| 8 | Address type not supported | The proxy cannot handle this address form | IPv6 target, or hostnames, on a proxy that lacks them | Send an IPv4 address, or use a fuller proxy |
1: general SOCKS server failure
The reply everyone eventually meets, and the least specific by design. The proxy accepted the request and could not fulfil it, and did not classify why. Operationally it almost always means the onward connection from the proxy to the destination failed: the target refused or timed out from where the proxy sits, the proxy's own internet path is broken, or the proxy is saturated. Distinguish them by trying a second destination through the same proxy. If everything fails, the proxy is the problem; if only one target fails, that target is unreachable or blocking from the proxy's network, and a different exit is the answer.
2: connection not allowed by ruleset
The proxy is healthy and refused on policy. SOCKS proxies commonly restrict which destination ports may be used, which addresses may be reached, and which source addresses may use them for what. A request for port 25 through a proxy that blocks mail, a destination on the operator's deny list, or a proxy that permits your address only for certain targets all produce this. There is nothing to fix on the client; the choice is a permitted port or destination, a different proxy, or a conversation with whoever runs it.
3 and 4: network and host unreachable
Both mean the proxy tried to route to the destination and could not. Host unreachable has one cause worth calling out: name resolution. If the client sent a hostname (SOCKS5 allows it) and the proxy could not resolve it, the reply is host unreachable, even though the same name resolves fine on your machine. The reverse problem is also common: a client that resolves the name locally and sends the proxy an address that only makes sense from the client's network. The convention that separates the two is the scheme: socks5:// means resolve locally, socks5h:// means send the name and let the proxy resolve it, and most tools that support SOCKS5 support both. For a target that is only reachable, or only resolvable, from the proxy's side, use socks5h.
5: connection refused
The clearest of the set. The proxy reached the destination host and the host said no on that port. The proxy did its job; the target is not listening there. Check the port, and check that the target is up.
6: TTL expired
The proxy's attempt to reach the destination timed out. Filtered paths and overloaded targets look identical from here; try the target through a different exit before deciding which.
7 and 8: command and address type not supported
SOCKS5 defines three commands. Nearly every proxy supports CONNECT. Far fewer support UDP ASSOCIATE, which applications such as games, VoIP, and some DNS setups need, and BIND is rarer still. A reply of 7 from a UDP-requiring application means the proxy is CONNECT-only, and no configuration on the client changes that; a proxy that supports UDP does. Reply 8 appears when the request names an address type the proxy does not handle, most often an IPv6 target on an IPv4-only proxy, or a hostname on a proxy that only accepts addresses.
The authentication failures
These happen before any reply byte, so they show up as different wording.
No acceptable methods (0xFF). The client offered a set of authentication methods and the proxy accepted none. The overwhelmingly common case is a proxy that requires a username and password receiving a client that offered only no-authentication, either because the credentials were left out of the URL or because the tool cannot do SOCKS5 authentication at all. Some browsers and many older tools fall into the second group. Supply the credentials in the URL (socks5h://user:pass@host:1080), or use IP authentication with the provider so that the proxy accepts your address without a login, or switch to a client that supports username and password. The IP-authentication route is described in proxy authentication without a password.
Authentication failed. The proxy chose username and password, received them, and rejected them. Wrong credentials, credentials for a different product or gateway, special characters that were not URL-encoded, or an IP-authenticated proxy receiving a request from an address that is not on the allowlist. Check the credentials against the provider's dashboard and the source address against the allowlist; our 407 guide covers the same traps on the HTTP side.
When it is not SOCKS at all
A large share of "SOCKS5 not working" reports are protocol mismatches. An HTTP proxy on port 8080 given a SOCKS5 handshake answers with an HTTP error or closes the connection; a SOCKS5 proxy on 1080 given an HTTP CONNECT line closes it. Clients report these as handshake failures, resets, or "connection closed by proxy", never as a numbered reply, because no SOCKS reply was ever sent. Port 1080 is conventionally SOCKS and 8080 or 3128 conventionally HTTP, and a checker that tests each protocol separately settles it in seconds.
SOCKS4 is the other mismatch. It has no real authentication, no IPv6, no UDP, and in its original form no hostnames (SOCKS4a added those). Its replies are numbered differently: 90 for granted, 91 for rejected or failed, 92 and 93 for identd problems. A client configured for SOCKS4 that sends a hostname to a strict SOCKS4 proxy fails outright. SOCKS4 versus SOCKS5 covers the differences; the practical rule is to use SOCKS5 wherever the proxy offers it.
How each client reports it
| Client | How the failure appears |
|---|---|
| curl | Exit code 97, "Proxy handshake error", with the SOCKS detail in -v output |
| Chrome and Chromium | ERR_SOCKS_CONNECTION_FAILED (net error -120) for most replies; ERR_SOCKS_CONNECTION_HOST_UNREACHABLE (-121) for reply 4 |
| Firefox | "The proxy server is refusing connections" when the proxy cannot be reached; SOCKS reply failures surface as generic connection errors |
OpenSSH -D dynamic forwarding | Acts as the SOCKS server itself: channel N: open failed: connect failed: Connection refused when the far end refuses, administratively prohibited: open failed when the server forbids the forward |
| proxychains | <--denied after the proxy in the chain line when it refused, <--timeout when it did not answer |
| Python PySocks | SOCKS5Error: 0x01: General SOCKS server failure and the other codes by number; SOCKS5AuthError for authentication; ProxyConnectionError when the proxy itself is unreachable |
The mapping is what makes this useful. A Chrome ERR_SOCKS_CONNECTION_HOST_UNREACHABLE is reply 4 and the DNS discussion above applies. A PySocks 0x02 is a ruleset denial and no retry will change it. A proxychains <--denied is the same ruleset denial seen from a chain.
Testing, and picking a proxy that does not do this
Test from the shell before blaming the application:
curl -v --socks5-hostname proxy.example.com:1080 -U user:pass https://example.com/ -o /dev/null
The verbose output shows the negotiation and names the SOCKS failure when there is one. --socks5-hostname resolves the target on the proxy side; --socks5 resolves it locally, which is the difference between socks5h:// and socks5:// in URL form. Our proxy checker runs the SOCKS4 and SOCKS5 handshakes separately for any address and reports which ones succeeded, which is the quickest way to catch an HTTP proxy masquerading as SOCKS on a public list.
Free SOCKS5 proxies produce reply 1 and the authentication failures constantly, for the reason free proxies produce everything: the address is shared by a crowd, the upstream is saturated, and the operator's rules are unknown. Our free SOCKS5 list shows the last successful handshake for each entry and is fine for a test. For anything that has to work, every plan we sell speaks SOCKS5 with username and password or IP authentication, supports hostnames and IPv6 targets, and comes from a network where reply 2 is not a surprise. The SOCKS5 explainer covers what the protocol gives you over HTTP proxies and when it matters.
The replies, one line each
Reply 1 is "could not connect onward" and usually the proxy or its upstream. Reply 2 is policy and cannot be retried away. Reply 4 is often DNS, fixed with socks5h. Reply 5 is the target's port. Reply 7 is a CONNECT-only proxy asked for UDP. 0xFF and authentication failures are credentials or the allowlist. And a failure with no number at all is a proxy that is not speaking SOCKS.