curl socks5h versus socks5: who resolves the hostname

People treat socks5h as socks5 with a friendlier spelling, and expect both to send the same request to the same place. The extra letter moves the DNS lookup instead. On a machine whose resolver and whose proxy sit in different networks, that is the difference between a request that works and one that fails.

One letter, two resolvers

The scheme decides where the destination name becomes an address. Local resolution uses the resolver configured on your machine. Remote resolution puts the hostname inside the SOCKS request, and the proxy looks it up with its own resolver and its own view of the network. Both forms still connect to the same proxy address on the same port, so the difference is in the request body, not in the path.

Nothing about the scheme changes encryption or authentication; only the DNS path moves. That is why the letter is easy to ignore and expensive to get wrong.

Same proxy, different request

The two invocations differ by a single character. Everything else about them is identical:

curl --proxy socks5://proxy.example:1080 https://service.example/
curl --proxy socks5h://proxy.example:1080 https://service.example/

The curl proxy reference documents these schemes separately, which is the authoritative reason not to treat them as aliases. Run both against a harmless endpoint you are authorized to use and read the difference. A successful remote lookup says nothing about other applications, because browsers, package managers and language runtimes each choose for themselves.

The proxy's own name is resolved locally

In that command, proxy.example has to become an address before anything else happens, and that lookup is always local. Moving service.example's resolution to the proxy does nothing for the proxy's own name, which still needs a resolver your machine can reach. This is where a VPN changes the picture.

If the proxy name resolves only inside the tunnel, the connection depends on the tunnel being up before curl starts. Which scheme wins then depends on which side can answer. When your machine cannot resolve the destination but the proxy can, socks5 fails and socks5h succeeds. When your machine resolves it through the tunnel and the proxy cannot, socks5 works and socks5h fails.

The scheme does not place the connection to the proxy inside or outside the VPN; the routing table does that, and the scheme never sees it. That is why one tunnel can fix one scheme and break the other on the same machine. The letter decides only who asks the question.

What each side can resolve

A public proxy cannot resolve a company-only name, so sending it the hostname fails at the proxy and surfaces as a proxy error rather than a DNS error locally. A proxy inside the same private network usually can resolve those names, which is where socks5h earns its keep. Choose the resolver location from the policy you actually need, because remote DNS is not automatically more capable and it does hand the name to a third party. For a public destination either form works, so prefer the one your other tools already use.

Write that choice into the runbook rather than into a comment, and keep credentials out of shared histories and diagnostic output. Then change one variable at a time: same destination, same binary, same resolver, one letter.

Which binary answered

Two curl binaries on the same machine can differ in version and build features. On a Unix-like shell, type -a curl lists every match on the path and curl --version shows the features of the one that would run. A wrapper script or an alias earlier in the path is a common reason results do not match the binary you think you are testing.

An unsupported scheme, a proxy that cannot resolve the name, and an unreachable destination are three different errors, so read the message before changing the letter. A build without the socks5h syntax reports the proxy string as unsupported, which is not the same as a name that failed to resolve. Do not turn one old report about a system curl into a permanent rule about every platform.