Proxy Troubleshooting Checklist

Proxy failures present as a small number of symptoms with a large number of causes, which is what makes triage hard. This is an ordered checklist, from the most likely causes to the least, with the command to run at each step.

Work top to bottom. Most incidents resolve in the first three steps.

Step 1: Confirm the exit address

The single most useful check, and the one that catches the most problems.

curl -s -x "http://USER:PASS@HOST:PORT" https://api.ipify.org

Four outcomes:

Run this through the actual client where possible, not only through curl. A working curl and a failing application usually means the client is not applying the proxy, which is step 2.

Step 2: Confirm the client is using it

The most common cause of "the proxy does not work": it is not being used.

Check the environment and configuration precedence:

env | grep -i -E 'http_proxy|https_proxy|no_proxy|all_proxy'

Three things to verify. no_proxy does not contain the target host, because that silently bypasses the proxy for that domain. The scheme is correct, since https_proxy pointing at an HTTP proxy is normal and correct, while an SOCKS proxy must be declared as socks5. And the client honours the environment at all, because some libraries read it and some require explicit configuration.

Where the client has its own proxy setting, it usually wins over the environment. Set one, not both.

Step 3: Distinguish an origin 403 from a proxy 403

A 403 with the proxy working is a different problem from a 403 caused by the proxy.

echo "== direct =="; curl -s -o /dev/null -w '%{http_code}\n' https://TARGET/PATH
echo "== proxied =="; curl -s -o /dev/null -w '%{http_code}\n' -x "http://USER:PASS@HOST:PORT" https://TARGET/PATH

The second row is the one that sends teams into an address-rotation loop that cannot help. If the direct request is also refused, the problem is headers, rate or behaviour, which is covered in Rate Limiting vs Blocking and Fixing 403 Forbidden.

Step 4: Connection failures

Symptom: timeouts, CONNECT errors, or the connection refused immediately.

CONNECT tunnel failed or 407. Authentication. Either the credentials are wrong, the endpoint expects IP allowlisting instead, or the credential format is wrong. The two styles and their formats are in Proxy Authentication Explained.

Connection timed out. The host or port is unreachable from your network. Check the port, then check whether your egress firewall blocks it. Some networks block non-standard ports.

Connection refused instantly. Reachable but not listening on that port. Usually a wrong port, or a protocol mismatch: an HTTP request to a SOCKS5 port.

TLS handshake errors. Usually a scheme mismatch or a transparent proxy interfering. Test with an explicit socks5h:// scheme, where the h sends DNS resolution through the proxy.

Works for HTTP, fails for HTTPS. The proxy does not support CONNECT, which is required for HTTPS tunnelling.

Step 5: Session and rotation problems

Symptom: the address changes when it should not, or stays when it should rotate.

The usual cause is a session parameter that is missing, malformed, or being stripped. Two checks:

for i in 1 2 3; do
  curl -s -x "http://USER-session-abc123:PASS@HOST:PORT" https://api.ipify.org; echo
done

Three identical addresses means the session is pinned correctly. Three different addresses means the session parameter is not being applied, which is a credential format problem rather than a provider fault. The format is in Understanding Proxy Session IDs.

The reverse case, where a rotating pool returns one address, usually means the pool's rotation setting is per-session and the client is reusing a connection. Force a new connection per request.

Step 6: Country and geo mismatches

Symptom: the exit address works but the data is wrong, or a target behaves as though you are elsewhere.

curl -s -x "http://USER:PASS@HOST:PORT" https://ipinfo.io/json

Check the country, the region and the ASN. Three failure modes:

The address is in the wrong country. The pool is not restricted to the country requested. Confirm with the provider, and verify per-request rather than assuming.

The country is right but the region is wrong. Matters for localised results, as described in Geo-Targeted SERP Testing.

The ASN is hosting rather than consumer. The address is datacenter, not residential, whatever the pool is labelled. The distinction is in Datacenter vs Residential vs Mobile Proxies.

Step 7: DNS and leaks

Symptom: the target sees something other than your exit address, or geo-located content is inconsistent with the address.

Run the WebRTC Leak Test from a browser. If the host address appears, the leak defeats every assignment on that machine.

For DNS, three modes exist and behave differently. Local resolution means your ISP resolves the name, which can leak your location through the resolver. Remote resolution through the proxy is what socks5h provides. The safe default for anything location-sensitive is remote resolution.

Step 8: Performance

Symptom: it works but slowly.

Four causes, in order of frequency. A geographically distant endpoint, where the round trip is the latency floor. A saturated provider, visible as variable latency across requests. Client-side overhead, where a browser render dominates the measurement. And a misdiagnosed timeout, where the request succeeds but the client cancels early.

Measure p50 and p95 separately, since the mean hides the tail, as noted in Monitoring Scraper Health.

The quick reference

Before escalating to the provider

Gather four facts, which is what their support will ask for: the exact command and output from step 1, the endpoint and port, the timestamp with timezone, and whether the failure is consistent or intermittent. That set turns a support round trip into a diagnosis.

The tooling referenced above is available as the Proxy Checker, IP Lookup and WebRTC Leak Test. For the solution context, see Proxy Management.