cURL Proxy Errors Explained: Exit Codes 5, 7, 28, 35, 56 and 97

This page is for when the command fails. For the working syntax — flags, SOCKS5, geo checks — see the cURL integration page.

Start with verbose output

curl -v -x http://USERNAME:PASSWORD@PROXY_HOST:PROXY_PORT https://example.com -o /dev/null

# Typical healthy output:
# * Connected to PROXY_HOST (203.0.113.10) port PROXY_PORT
# * CONNECT tunnel: HTTP/1.1 negotiated
# > CONNECT example.com:443 HTTP/1.1
# < HTTP/1.1 200 Connection established
# * CONNECT phase completed

Read the output top to bottom and stop at the first line that is not what you expected. That line is the problem; everything after it is consequence.

Exit codes at a glance

curl: (5) Could not resolve proxy

cURL could not turn the proxy hostname into an address. Check the spelling, then run nslookup PROXY_HOST. If a stray environment variable is pointing cURL at an old proxy you forgot about, -v shows its name here — see the section on environment variables below.

curl: (7) Failed to connect to proxy

• Connection refused arrives instantly: something answered and said nothing is listening. Almost always the wrong port — HTTP and SOCKS5 endpoints often use different ones.
• A hang, then code 7 or 28, means nothing answered at all. A firewall is dropping the packets silently; test from another network such as a phone hotspot.
• Expired or exhausted plans can close the port rather than return an error, so check the dashboard before debugging your network.

curl: (56) CONNECT tunnel failed

This is the most common proxy error and the most informative, because it quotes the proxy's answer. The number at the end of the message is an HTTP status from the proxy, not from the website.

# A password containing @ or : must be encoded in the URL
curl -x "http://USERNAME:p%40ss%3Aword@PROXY_HOST:PROXY_PORT" https://example.com

# Or pass it separately, where no encoding is needed
curl -x http://PROXY_HOST:PROXY_PORT -U "USERNAME:p@ss:word" https://example.com

Remember the flag distinction: -U / --proxy-user authenticates to the proxy, while -u / --user authenticates to the website. Credentials passed with -u never reach the proxy, which then answers 407 no matter how correct they are.

curl: (35) SSL connect error

Usually the proxy URL starts with https:// when the proxy speaks plain HTTP. cURL tries to open TLS to the proxy itself, the proxy replies in plaintext, and the handshake fails. For almost every proxy product the right scheme is http://, even for HTTPS targets — the target's TLS runs inside the tunnel. Only use https:// for a proxy that explicitly supports TLS on the proxy hop.

curl: (97) Proxy handshake error

A SOCKS negotiation failed before any data moved. Check that the endpoint really is SOCKS5 rather than HTTP, that the port is the SOCKS port, and that the credentials are right — SOCKS5 password authentication fails here rather than with a 407. Prefer socks5h:// so the proxy resolves the hostname; plain socks5:// resolves it on your machine, which can also produce code 6 for hosts only the proxy can resolve.

curl -v -x socks5h://USERNAME:PASSWORD@PROXY_HOST:SOCKS_PORT https://api.ipify.org

Environment variables that override you

cURL reads proxy settings from the environment, and a forgotten variable is a classic source of errors that seem to ignore your flags.

• `http_proxy` is only read in lowercase. HTTP_PROXY is ignored on purpose, for CGI security reasons.
• `HTTPS_PROXY` / https_proxy covers HTTPS targets; `ALL_PROXY` applies to everything else.
• `NO_PROXY` lists hosts that bypass the proxy — handy for internal services, confusing when a target is on it by accident.
• `-x` on the command line always wins. --noproxy '*' disables the proxy entirely for one call, which is the quickest way to prove whether the proxy is involved at all.

Windows: curl vs curl.exe

In Windows PowerShell 5.1, curl is an alias for Invoke-WebRequest, which does not understand -x, -U or -v and fails with a parameter error that looks nothing like a proxy problem. Type curl.exe to use the real cURL that ships with Windows 10 and 11. PowerShell 7 removed the alias, but curl.exe works everywhere and saves the question.

Proxy works in cURL but not in your app

Then the proxy is fine and the difference is in the client. The usual suspects are a library that does not send credentials on CONNECT, a headless browser that drops them — see ERR_TUNNEL_CONNECTION_FAILED — or an https:// scheme in a config file. Compare the exact proxy URL the application uses with the one that worked here, character by character.