Troubleshooting proxy errors

This page covers the errors you can run into when you connect to netdash, each under the message your client prints, with its causes and the fix. Start with a proxy 407 error if you see one: it means the gateway didn't accept the username or password, and nothing else works until that is fixed.

Quick checks

Run through this list before you dig into a specific error:

• The host and port belong to the plan you bought. Compare them with the endpoint table.
• The proxy URL starts with http://, not https://, also for HTTPS websites.
• The username contains -cc- and an uppercase country code, for example USERNAME-cc-US.
• The United Kingdom is GB, not UK.
• If you use -session-, the username also has -ttl-, and the session ID has only letters and digits.
• The plan you're sending traffic to has GB left in the dashboard.
• The URL you request is in quotes when you run curl in a shell.
• Your network allows outbound connections to the gateway's port.

To test outside your application, run one request with curl. If it prints an IP address, the gateway and your credentials work, and the problem is in your client's configuration:

curl --max-time 30 -x "http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000" \
  "https://api.ipify.org?format=json"

407 Proxy Authentication Required: fixing a proxy 407 error

The gateway answers 407 Proxy Authentication Required when it doesn't accept the credentials it received. How the error looks depends on the client:

Why the gateway returns 407

• Wrong password. Copy it again from the dashboard. When you paste it into a .env file, check for spaces or line breaks around it.
• Mistyped base username. The part before -cc- must match your username in the dashboard exactly.
• Usernames outside the documented syntax. A missing -cc-, UK instead of GB, -session- without -ttl-, or a hyphen inside the session ID aren't supported. Correct them to the username syntax before you look further.
• Credentials that never reach the gateway. Browser automation tools take the proxy server and the credentials as separate settings. Playwright's proxy option, for example, has server, username and password fields. With Puppeteer the authentication step is easy to miss, and Selenium with Chrome needs a local forwarder: see the Puppeteer and Selenium guides.
• Unencoded special characters. If a value contains @, : or /, percent-encode it in the proxy URL.

Find the cause with curl -v

Send one request with curl's verbose flag and read the gateway's answer:

curl -v --max-time 30 -x "http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000" "https://api.ipify.org?format=json"

In verbose output, lines starting with > are what curl sent, lines starting with < are what it received, and lines starting with * are curl's own notes. For an HTTPS website, curl first sends > CONNECT api.ipify.org:443 HTTP/1.1 to the gateway. The lines starting with < right after that block are the gateway's answer to the CONNECT request:

• < HTTP/1.1 407 ... followed by * CONNECT tunnel failed, response 407: the gateway rejected the username or password. Fix them using the causes above.
• < HTTP/1.1 200 ... followed by * CONNECT tunnel established, response 200: the gateway accepted your credentials. Anything that fails after this point happens inside the tunnel, between your client and the website.

If curl works and your application doesn't, compare the exact username your application sends with the one in the curl command.

ERR_TUNNEL_CONNECTION_FAILED in a browser

Chromium-based browsers, including Chromium driven by Playwright, Puppeteer or Selenium, report net::ERR_TUNNEL_CONNECTION_FAILED when a tunnel through the proxy couldn't be established. With netdash, start with the credentials:

1. Run the same username and password through curl, as in the 407 section.
2. If curl prints an IP and the browser fails, the browser is most likely not receiving the credentials. Pass them through Playwright's or Puppeteer's authentication setting, not inside the --proxy-server value; Selenium with Chrome has no such setting, so use a local forwarder. The Playwright, Puppeteer and Selenium guides show how.
3. If curl fails too, work through the 407 causes above.

net::ERR_PROXY_CONNECTION_FAILED is different: the browser couldn't connect to the proxy server at all. Treat it like a timeout, below.

Requests skip the proxy

The request works, but the IP it prints isn't a netdash exit IP: it's your own address, or the address of another proxy set in your environment. The client didn't send the request through netdash:

Setting HTTPS_PROXY for the whole process is not a good fix either. A global HTTPS_PROXY applies to every request the process makes, including calls to model APIs and package registries. Those requests would go through netdash and count against your balance. Set the proxy on the client that fetches websites instead.

Timeouts and connection refused

Typical messages: curl: (28) Connection timed out after ..., curl: (7) Failed to connect to scale-us.netdash.io port 2000, curl: (5) Could not resolve proxy: ..., or a client-side ConnectTimeout.

Why connections time out

• An outbound firewall. The gateways listen on ports 1000, 2000, 3000 and 4000. Corporate networks, some CI runners and some hosting environments restrict outbound ports. If curl -v stops after the * Trying ... line, the connection to the gateway isn't getting through.
• A host or port typo. Could not resolve proxy means the gateway host name is wrong. Copy host and port from the endpoint table.
• No timeout, or a very short one. requests, for example, doesn't time out unless you set a timeout. The examples on this site use 30 seconds.
• A sticky exit IP became unavailable. Requests in that session may stall or fail. Start a new session ID; see sessions.

Rule out a firewall

Test from a different network, for example your laptop instead of a CI runner, to rule out a firewall. If the same curl command works there, ask the network's administrator to allow outbound connections to the gateway host and port you use.

TLS and certificate errors

Typical messages: ProxyError: Unable to connect to proxy. Your proxy appears to only use HTTP and not HTTPS with SSLError ... WRONG_VERSION_NUMBER in Python, curl: (35) ... with a TLS error, or CERTIFICATE_VERIFY_FAILED.

Why TLS fails

• https:// as the proxy scheme. The client then tries to start TLS with the gateway itself. netdash is an HTTP proxy, so this fails. In Python, also check HTTPS_PROXY and ALL_PROXY in the environment, which can carry an https:// value without your code knowing.
• Certificate verification fails for the website. netdash carries HTTPS in a CONNECT tunnel, so the certificate your client checks is the website's own. A failure points at your environment, such as an outdated CA bundle or security software on your machine that inspects HTTPS, or at the website.

Fix it without disabling verification

Use http:// as the proxy scheme for every website. For certificate errors, update the CA certificates your client uses (for Python requests, upgrade certifi), then retry.

Never disable TLS verification to make an error go away. verify=False in Python, rejectUnauthorized: false in Node.js or NODE_TLS_REJECT_UNAUTHORIZED=0 hide the cause and let anyone between you and the website read and change the traffic.

Wrong exit country

The exit IP is in a different country from the one you asked for.

• Check the code. It must be an uppercase ISO 3166-1 alpha-2 code: GB for the United Kingdom, not UK. With a misspelled country code, the country you meant never reaches the gateway; a username without -cc- isn't supported.
• Check the gateway. Use -us for exits in the Americas and -eu for exits in Europe. For other countries, ask support which gateway to use.
• Check the lookup. Geolocation databases can disagree about an IP's country. Look up the exit IP in the source the website uses, if you know it, before you conclude the exit is wrong.

Country targeting has the full rules and examples.

A sticky session changed IP

The exit IP changed although the username has a session ID.

• The exit IP became unavailable. A sticky session keeps its IP only while that IP stays available. Start the step again with a new session ID.
• The lifetime ended. After -ttl- minutes, don't count on the same IP. Choose a lifetime that covers the whole task.
• The session ID differs between requests. A typo, an ID generated per request instead of per task, or a separate ID per worker when you expected one shared session.

Sessions explains how to detect a changed IP and restart cleanly.

zsh: no matches found

% curl -x http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000 https://api.ipify.org?format=json
zsh: no matches found: https://api.ipify.org?format=json

zsh treats ? and * in an unquoted word as filename patterns and, by default, stops with an error when no file matches. Other shells cause related problems: an unquoted & ends the command in bash and runs it in the background, so every query parameter after it is lost. Put the proxy URL and the website URL in quotes:

curl --max-time 30 -x "http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000" "https://api.ipify.org?format=json"

Double quotes still let the shell expand $, and in interactive bash and zsh also !. If your password contains either character, use single quotes around the proxy URL instead.

Requests fail on one plan

Your username and password are the same on every residential and mobile plan, but each plan keeps its own GB balance. If requests fail on one plan but work on another, check that plan's balance on the Residential (or Mobile) page in the dashboard. You can add GB to a plan with a new order in the shop.

The website returns 403, 429 or a challenge page

A 403, 429 or challenge page that arrives through an established tunnel is the website's answer to your request: netdash delivered the request and passes the response back unchanged. In curl -v output, that response comes after CONNECT tunnel established, response 200.

What to do depends on the answer:

• 429 Too Many Requests: you're sending more than the website accepts. Slow down, and if the response has a Retry-After header, wait at least that long before the next request.
• 403 Forbidden or a challenge page: stop. Check the website's terms and robots.txt, and use its official API if it has one.

Still stuck?

Email support and include these details:

• Plan and gateway host:port
• The username you used, without the password
• Time of the failure, in UTC
• The website's domain
• The full error message
• Client and version, for example curl, Python requests or Playwright

Leave your password out of every message. The button below opens an email with these fields already in place.

We don't currently publish a live status page. Service status lists the first checks, and contact has every way to reach us, including live chat on this site.

Related

• Proxy format reference

  Endpoints, username syntax and output formats.

• Sessions

  Sticky lifetimes, session IDs and early IP changes.

• Country targeting

  Country codes, GB for the UK and gateway choice.