Proxy DNS Troubleshooting Checklist: NXDOMAIN, SOCKS5h, and IPv6

“DNS error” is often too vague to be actionable. The fastest route to a fix is to identify which name failed, where it was resolved, and whether the failure occurred before or after the proxy produced a response.

The four stages to separate

1. Resolve the proxy endpoint. The client usually needs an address for proxy.example.net before it can open a connection.
2. Connect to the proxy. DNS success does not prove the proxy port is reachable.
3. Resolve the destination. This can happen locally or on the proxy side.
4. Connect from the proxy to the destination. A valid DNS answer can still lead to routing, firewall, TLS, or target-policy failure.

Never collapse all four stages into “the proxy is down.”

Start with an evidence record

UTC time:
Client operating system:
Client and version:
Network, VPN, or container state:
Proxy protocol:
Proxy endpoint hostname and port:
Proxy hostname A/AAAA result:
Target hostname:
Target DNS mode: local | proxy-side | unknown
Exact process exit code:
Exact error text:
HTTP status, if any:
Requested geography and session mode:

Keep credentials out of tickets and shell history.

Step 1: resolve the proxy hostname locally

getent ahosts proxy.example.net
dig +short proxy.example.net A
dig +short proxy.example.net AAAA

If this lookup fails, check spelling, environment variables, search domains, split-horizon DNS, VPN filtering, container resolver configuration, upstream outages, and IPv4/IPv6 availability.

Step 2: test the proxy port

nc -vz proxy.example.net 8001

Interpret errors precisely:

• timeout: routing, firewall, filtering, or unavailable service
• connection refused: address reachable but no listener accepted the port
• TLS certificate error: relevant to an HTTPS proxy connection
• 407 Proxy Authentication Required: an HTTP proxy was reached and requested credentials

An HTTP 407 is not a DNS failure. See RFC 9110↗.

Step 3: determine who resolves the target

HTTP forward proxy and CONNECT

For ordinary HTTP proxy requests, the client sends a target authority to the proxy. For HTTPS tunneling, the client commonly sends CONNECT target.example:443; the proxy then needs to reach that authority. Implementations differ, so preserve the actual client trace rather than assuming a universal resolver path.

SOCKS5 local resolution

curl --socks5 'proxy.example.net:1080' \
  --connect-timeout 10 --max-time 30 \
  'https://example.com/'

With curl, --socks5 resolves the destination locally.

SOCKS5 proxy-side resolution

curl --socks5-hostname 'proxy.example.net:1080' \
  --connect-timeout 10 --max-time 30 \
  'https://example.com/'

curl --proxy 'socks5h://proxy.example.net:1080' \
  'https://example.com/'

The hostname form delegates destination resolution to the SOCKS5 proxy. See the curl manual↗ and SOCKS5 specification↗.

Controlled comparison matrix

IPv4 and IPv6 mismatches

A hostname can return both A and AAAA records. Failures can appear when the client prefers IPv6 but lacks a working path, the proxy listener is IPv4-only, or the proxy resolves a target to an unreachable IPv6 address.

curl -4 --proxy 'http://proxy.example.net:8001' 'https://example.com/'
curl -6 --proxy 'http://proxy.example.net:8001' 'https://example.com/'

Do not force one family permanently until the other path is understood.

NXDOMAIN, SERVFAIL, and timeout are different

• NXDOMAIN: the resolver says the name does not exist
• SERVFAIL: the resolver could not complete the query
• timeout: no usable response arrived within the client limit
• empty answer: the name may exist without the requested record type

Preserve the resolver response rather than paraphrasing every result as “not found.”

DNS caching can hide the result

The operating system, runtime, browser, local forwarder, container, proxy, and upstream resolver can each cache answers. Record TTLs where possible and avoid flushing production caches without understanding the impact.

Do not misuse --resolve

curl --resolve 'example.com:443:192.0.2.10' 'https://example.com/'

The address is documentation-only. --resolve can isolate a local DNS variable for an authorized target, but it can bypass load balancing or select the wrong address family. It does not change how the proxy endpoint hostname is resolved.

Browser-specific checks

When curl works but a browser fails, capture browser version, launch proxy settings, secure-DNS policy, browser trace, connection reuse, final URL, and exact error name. Test a fresh context or process so existing connections do not hide route changes.

Common mistakes

• treating 407 as DNS
• testing only the real target
• changing protocol while debugging
• disabling TLS validation
• publishing real endpoints and credentials

Decision checklist

1. Can the client resolve the proxy hostname?
2. Can it connect to the correct port?
3. Did the proxy return an HTTP response?
4. Who resolves the destination?
5. Do A and AAAA paths differ?
6. Does a neutral HTTPS target work?
7. Does the permitted real target behave differently?
8. Are caches or reused connections affecting the comparison?

Related BytesFlows resources

• Detailed local-versus-remote DNS guide
• HTTP vs SOCKS5 residential proxies
• Proxy TLS certificate troubleshooting
• Proxy environment variables with curl
• Proxy setup guide

Before applying the checklist

The commands use documentation hostnames and are intended as diagnostic patterns. Replace them with endpoints and targets you are authorized to test, then record the observed route, resolver behavior, geography, and response from your own environment before drawing account-specific conclusions.