$
Sign inSign up

https-proxy-agent and socks-proxy-agent Errors

Both agents take the proxy as a single URL string. Most errors start right there: the string does not parse, the password breaks the address, or the scheme is wrong.

Updated · Prokso editorial team

Key takeaways
  • Both agents parse the proxy string as a URL, so you need a full address with a scheme
  • Encode special characters in the username and password with encodeURIComponent, or the address breaks or the host changes
  • For SOCKS5 use socks5h:// so that the proxy resolves the site name

What the error means

The https-proxy-agent and socks-proxy-agent packages parse the proxy string with the standard URL class. If the string is not a valid address, Node.js throws TypeError: Invalid URL with the code ERR_INVALID_URL. This happens, for example, when the password contains a / character or the port is above 65535.

It is worse when there is no error at all. The characters @ and # in a password do not break parsing, but they change the address: in our test, a string with the password p@ss#1 turned into the host ss. The program goes to a host that does not exist and then fails with ENOTFOUND.

Both agents decode the username and password with decodeURIComponent. So special characters must be encoded before you put them into the string, and the agent restores them. In socks-proxy-agent the scheme also decides who turns the site name into an IP: with socks5 your computer does it, with socks5h the proxy does.

Causes

  • A string without a scheme. The host:port:username:password format is not a URL. socks-proxy-agent then answers with the TypeError "A "socks" protocol must be specified!".
  • Unencoded special characters in the password. The characters / ? # @ : % and a space break the address or silently change the host.
  • A wrong username or password. The HTTP gateway answers "HTTP/1.1 407 NO_USER", and the socks library on port 824 reports "Socks5 Authentication failed".
  • The scheme does not match the port. Use http:// for port 823 and socks5h:// for port 824; ports 10000-20000 accept both protocols.
  • socks5 instead of socks5h. Your DNS, not the proxy, resolves the site address, so the site may be reached at an IP picked for your network rather than for the proxy country.

How to fix it

  1. Write the full string with a scheme: http://USERNAME:PASSWORD@gw.prokso.com:823 for https-proxy-agent and socks5h://USERNAME:PASSWORD@gw.prokso.com:824 for socks-proxy-agent.
  2. Build the string with encoding: `http://${encodeURIComponent(login)}:${encodeURIComponent(password)}@gw.prokso.com:823`. Then no password character can break the address.
  3. For a 407, copy the username and password from the dashboard again, without spaces. Check the parameters in the username (country, city, session) against the username, ports and parameters page. More about the code is on the 407 error page.
  4. If you would rather not put the password into the string, turn on IP access in the dashboard (up to 5 addresses per plan) and connect without a username.
  5. For SOCKS5 always use socks5h://. What to do when the SOCKS server answers with a general error is on the SOCKS5 general failure page.

How to check that it works

Before running, print new URL(string).hostname: it should be gw.prokso.com. Then test the string in the proxy checker and send a request through the agent to https://prokso.com/ip.

Two-minute diagnosis

First paste the line into the proxy checker. If the proxy works there, the cause is in your app or its settings. If not, test the line from a terminal:

curl -v -x "http://USERNAME:PASSWORD@gw.prokso.com:823" https://api.ipify.org
  • A < HTTP/1.1 407 line right after CONNECT means the proxy answered. The name after the code, for example NO_USER, points to the cause.
  • The proxy answered CONNECT with 200 and then another code arrived - the proxy works, and that answer came from the website.
  • No answer at all, only a timeout - the connection never reached the proxy: check the host, port and network.

Setup guides where this error comes up

FAQ

What is the difference between socks5 and socks5h in socks-proxy-agent?

In the package source, with socks5 your computer resolves the site name to an IP, with socks5h and plain socks the proxy does. More about the protocol is in the glossary: <a href="/en/glossary/socks5">SOCKS5</a>.

Do I need to encode the username, not only the password?

Yes, if the username has special characters. The agents decode both parts, so encodeURIComponent on the username does no harm.

How do I plug the agent into my code?

Pass the agent to the agent option of the http and https modules, or to httpsAgent in axios. Examples are in the <a href="/en/guide/nodejs">Node.js guide</a>.

Other proxy errors

407 Proxy Authentication Required403 Forbidden429 Too Many Requests502 Bad Gateway503 Service UnavailableERR_PROXY_CONNECTION_FAILEDERR_TUNNEL_CONNECTION_FAILEDProxy timeoutCloudflare 1015Cloudflare 1020Google: unusual traffic400 Bad Request401 Unauthorized404 Not Found Through a Proxy504 Gateway Timeout444 No ResponseCloudflare 1006, 1007, 1008Cloudflare 1010Cloudflare 1012Cloudflare 522Cloudflare 524SOCKS5 general failureSOCKS5 connection refusedSSL and Certificate ErrorsECONNRESET and ECONNREFUSEDProxyError in Python requestsSSLError in Python Through a ProxyMissing Dependencies for SOCKS SupportProxy Errors in httpx and aiohttpaxios: socket hang upTypeError: fetch failedHTTP_PROXY, HTTPS_PROXY and NO_PROXYERR_NO_SUPPORTED_PROXIESERR_SOCKS_CONNECTION_FAILEDProxy login in Puppeteer and PlaywrightProxy login in Seleniumcurl proxy error codesProxy traffic runs out fastProxy shows the wrong locationSticky IP changed earlyAll error codes

Residential $1.59, mobile $2.50, datacenter $0.65 per GB

Sign up in a minute, get access right after payment.

Create account