How to Fix Proxy Error 407 When Using Credentials in Playwright

Proxy error 407 occurs when a proxy server requires authentication but has not received valid credentials. In Playwright, this situation is often related to the configured username, password, proxy address, or authentication method supported by the browser.

To resolve it correctly, you need to distinguish proxy errors from website login errors and connection issues. This article explains how to configure a Playwright proxy, investigate the causes, and establish a safe diagnostic process.

What Is the 407 Proxy Authentication Required Error?

Proxy Authentication Required is the message associated with HTTP status code 407. A proxy uses this response to ask the client to provide appropriate credentials before forwarding traffic to the destination server.

Under HTTP authentication, the response may contain a Proxy-Authenticate field indicating the accepted authentication method. The browser then performs authentication according to its configuration and supported capabilities.

It is important to distinguish the following cases:

• 407: an authentication request from the proxy.
• 401: usually an authentication request from the resource server.
• 403: the request was denied; this alone is not enough to conclude that the proxy password is incorrect.

When accessing an HTTPS website, the browser usually needs to establish a CONNECT tunnel through an HTTP proxy. If authentication fails at this stage, Playwright may report a navigation or tunnel error rather than provide a page response with a 407 status.

Common Causes When Using a Proxy with Credentials

Incorrect or No Longer Valid Credentials

The username may need to include routing information according to the provider's conventions. A missing component in the username can cause authentication to fail even if the password is correct.

You should also check whether the account is locked, the password has changed, the service has expired, or the access policy has recently been updated. Do not simply compare the username and password strings and conclude that the configuration is valid.

Credentials Configured in the Wrong Place

Embedding the username and password directly in the URL is not the preferred approach for configuring a Playwright browser. A clearer approach is to separate the proxy address, username, and password into individual properties in the proxy object.

Another common mistake is using httpCredentials to handle proxy authentication. This property handles HTTP authentication for the destination server within a browser context; it does not replace the username and password in the proxy configuration.

Incorrect Protocol or Connection Port

The protocol in the proxy address describes how to connect to the proxy, not the protocol of the website you want to open. Accessing an HTTPS website does not mean you must change the proxy address from http:// to https://.

Use the exact endpoint, protocol, and port specified by the provider. For SOCKS, do not assume that username and password authentication works the same way as with an HTTP proxy; check the browser's support and the specific configuration.

How to Configure a Playwright Proxy Correctly

Example with JavaScript and Chromium

The following example uses environment variables to keep secrets separate from the source code. PROXY_SERVER must contain the endpoint address with the appropriate protocol and port; PROXY_USERNAME and PROXY_PASSWORD contain the actual credentials.

import { chromium } from 'playwright';

const server = process.env.PROXY_SERVER;

const username = process.env.PROXY_USERNAME;

const password = process.env.PROXY_PASSWORD;

if (!server || !username || !password) { throw new Error('Missing proxy configuration in environment variables'); }

const browser = await chromium.launch({ proxy: { server, username, password } });

try { const context = await browser.newContext(); const page = await context.newPage(); await page.goto('https://example.com'); } finally { await browser.close(); }

In this configuration, server contains only the proxy address. Do not embed credentials in server when username and password are already provided separately.

The environment variable check in this example is suitable for services that require both a username and a password. If your provider uses a different convention, adjust the check according to its documentation.

Distinguish Between Browser and Context Scope

Playwright offers proxy options at both the browser launch level and the browser context level. Clearly identify which level your application uses, especially when working with multiple contexts or reusing a browser from another service.

For diagnosis, start with one browser, one context, and one test page. A minimal configuration helps determine whether the error originates from the proxy or the application's session management layer.

If you use Playwright Test, check the proxy settings in use, each project's configuration, and any overrides in the tests. Do not assume that configuration in one file always applies to every test process.

A Step-by-Step Process for Diagnosing Proxy Error 407

Verify the Endpoint and Access Policy

First, open the service dashboard to check the endpoint, port, account status, and authentication method. Some services use credentials, some use an IP allowlist, and others apply a combination of policies.

If the source IP needs to be allowlisted, check the outbound IP address of the machine actually running Playwright. A personal computer, a container, and a CI machine may access the Internet through different addresses.

Test the Proxy Outside Playwright

Use an HTTP tool that supports proxies, such as curl, to send a test request with the same endpoint and credentials. If Playwright is opening an HTTPS website, the test should also use HTTPS to check the tunnel establishment step.

If the independent test also reports an authentication requirement, prioritize checking the proxy service and credentials. If the standalone tool works but the browser fails, focus on the Playwright configuration, authentication mechanism, and runtime environment.

A successful curl result does not guarantee that the browser will behave the same way. The two tools may support different authentication methods or use different system settings.

Check Environment Variables and Special Characters

Passwords containing special characters may be interpreted by the shell when passed through commands or configuration files. Check how values are quoted in the deployment environment rather than modifying the password itself.

When passing username and password as separate properties, you should generally use the original values without manually URL-encoding them. Also check for spaces or newline characters introduced by secrets read from files.

Do not automatically trim whitespace from every password: spaces may be a valid part of the secret. Fix the configuration source once you have identified an extraneous character.

Compare the Working and Failing Environments

If the same code works on your local machine but fails in CI, compare the Playwright version, browser binary, supplied secrets, and network path. Also check for an intermediary corporate proxy.

Do not assume that the operating system's HTTP_PROXY or HTTPS_PROXY variables will automatically configure Playwright browser traffic correctly. Explicitly set the proxy option for the component making the request.

Read Logs and Identify the Layer Where the Error Occurs

You can monitor the requestfailed event and record the message from request.failure() to identify failed requests. For HTTP responses visible to the page, the response event helps you check the status and associated address.

However, authentication failures during tunnel establishment may not appear as ordinary page responses. In that case, combine errors from page.goto with browser logs and proxy-side logs, if available.

• Unable to connect to the endpoint: check DNS, the port, the firewall, and network accessibility.
• Authentication requested: check the username, password, and authentication method.
• Tunnel establishment failed: check CONNECT, permission to access the destination, and proxy policies.
• Only one website fails: also check the website's response and the service's access restrictions.

Do not treat every navigation error as a proxy 407 error. Identifying the correct failure layer helps you avoid unrelated configuration changes.

Fixes You Should Not Apply Indiscriminately

Manually Adding Proxy-Authorization to Page Headers

Do not use extraHTTPHeaders as the default solution for proxy authentication. Page request headers are not equivalent to the authentication mechanism handled by the browser, especially when an HTTPS tunnel is involved.

This approach also risks exposing secrets in logs or sending sensitive information to the wrong destination. Prioritize the proxy object and methods supported by Playwright.

Disabling Certificate Validation or Increasing Timeouts

Ignoring certificate errors does not resolve invalid proxy credentials. Similarly, increasing the timeout only extends the wait if the actual cause is an authentication failure.

Adjust certificate settings or timeouts only when there is evidence that the problem lies at that layer. Avoid combining multiple changes in a single test.

Repeatedly Retrying with the Same Configuration

Retries are useful for some temporary network errors, but they cannot fix an incorrect password. Repeated retries may also trigger access limits or account lockouts under the service's policies.

Once you identify an authentication error, stop the task, record the cause, and request a configuration check before running it again.

Protecting Credentials in Operation

Store proxy credentials in a secrets management system or controlled environment variables. Do not put passwords in source repositories, screenshots, error reports, or paths that may be logged.

When requesting technical support, share only the verified endpoint, the time the issue occurred, error messages with secrets removed, and the runtime environment. If credentials have been exposed, rotate them and update the affected tasks.

Conclusion

To resolve Proxy Authentication Required in Playwright, start with the endpoint and access permissions, then check the username, password, protocol, and configuration scope. Independent tests and appropriate logs will help distinguish service errors from integration errors.

Configuring proxy authentication through separate properties, protecting secrets, and addressing one evidence-backed cause at a time form the foundation for stable, maintainable Playwright proxy operation.