Proxy Authentication in Puppeteer and Playwright: Setup and Errors

What the error means

The --proxy-server flag accepts only a scheme, host and port. The Chromium source code drops a proxy address with a username and password, so the string http://USERNAME:PASSWORD@gw.prokso.com:823 ends with net::ERR_NO_SUPPORTED_PROXIES.

In Puppeteer, credentials are passed with page.authenticate({username, password}). According to the documentation, it provides credentials for HTTP authentication, and to do so it turns on request interception behind the scenes, which might affect performance. The method belongs to a page, so call it for each new page before page.goto().

In Playwright, the proxy is set with the proxy: {server, username, password} option. The documentation says HTTP(S) and SOCKSv5 are supported, the proxy can be set for the whole browser or for a single context, and the username and password are described only for HTTP(S) proxies. The short form gw.prokso.com:823 is considered an HTTP proxy.

Causes

• A username in --proxy-server. Chromium drops such an address, and the browser is left without a proxy: net::ERR_NO_SUPPORTED_PROXIES.
• Missing or wrong credentials. Code -338 net::ERR_INVALID_AUTH_CREDENTIALS in Chromium means credentials could not be established during HTTP authentication. Check that authentication is called and that the username and password are correct; about the code itself, see the 407 page.
• The browser did not reach the proxy. Code -130 net::ERR_PROXY_CONNECTION_FAILED means a connection to the proxy server could not be created: an error in resolving its name or in connecting a socket. In Firefox under Playwright, the counterpart is NS_ERROR_PROXY_CONNECTION_REFUSED: the connection attempt to a proxy failed.
• SOCKS5 with a username in Chromium. Chromium does not support authentication for SOCKSv5, so page.authenticate() will not help here: the handshake ends with a SOCKS error.
• The tunnel did not open. If the connection to the proxy works but CONNECT to the site fails, you get ERR_TUNNEL_CONNECTION_FAILED.

How to fix it

1. Puppeteer: launch with --proxy-server=http://gw.prokso.com:823, then call await page.authenticate({username: 'USERNAME', password: 'PASSWORD'}) before navigating to the site. A full example is in the Puppeteer guide.
2. Playwright: pass proxy: {server: 'http://gw.prokso.com:823', username: 'USERNAME', password: 'PASSWORD'} to launch(). Details in the Playwright guide.
3. For SOCKS5 in Chromium, turn on IP access (up to 5 addresses in the dashboard) and use socks5://gw.prokso.com:824 without a username, or switch to HTTP port 823 with a username.
4. If you need one IP for the whole script, use a port from the 10000-20000 range: it keeps a sticky IP for the session duration (1-120 min, 30 by default). More in sticky session.
5. If you see ERR_PROXY_CONNECTION_FAILED, check the host gw.prokso.com, the port and the network using the proxy connection error page.

How to check that it works

After launch, open https://prokso.com/ip in the same page and read the JSON: the ip, country and org fields should belong to the proxy, not to your own connection. You can see the same on the IP check page.

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

• Proxy setup in Puppeteer
• Proxy setup in Playwright
• Proxy setup in Browser Use
• Proxy setup in Crawl4AI