# SOCKS5 proxy errors: reply codes, missing support and DNS

> SOCKS5 errors explained: missing SOCKS support in requests, curl error 97, reply codes 0x01 to 0x08, and socks5 vs socks5h DNS. With fixes.

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

SOCKS5 protocol or client error: the exact message in each tool, the likely causes in order, and the fix that works.

**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

| Attribute | Value |
| --- | --- |
| 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?

1. Confirm SOCKS support: in Python, `pip show pysocks`; in Node.js, a SOCKS agent package.
2. Run the curl test below against the SOCKS5 port with `--socks5-hostname`.
3. Read the reply code or message.
4. Compare `socks5://` and `socks5h://` for the same target.

*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 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 for `http://` 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.

*Python requests over SOCKS5 (pip install "requests[socks]")*

```python
import requests

# socks5h:// sends the hostname to the proxy, so DNS resolves at the exit
proxy = "socks5h://USERNAME:PASSWORD@gw.crawlrelay.com: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](https://crawlrelay.com/docs/errors/cannot-connect-to-proxy/) · [curl guide](https://crawlrelay.com/docs/curl/) · [Python guide](https://crawlrelay.com/docs/python/).

## 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

- [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.