microsoft/playwright · error · Error

Browser does not support socks5 proxy authentication

Error message

Browser does not support socks5 proxy authentication

What it means

Thrown by normalizeProxySettings() when the proxy.server URL protocol is 'socks5:' and username or password is set. Chromium/Firefox pass-through of SOCKS5 credentials via launch flags is not supported by the browsers, so Playwright refuses the combination instead of dropping the credentials silently.

Source

Thrown at packages/playwright-core/src/server/browserContext.ts:828

}

export function normalizeProxySettings(proxy: types.ProxySettings): types.ProxySettings {
  let { server, bypass } = proxy;
  let url;
  try {
    // new URL('127.0.0.1:8080') throws
    // new URL('localhost:8080') fails to parse host or protocol
    // In both of these cases, we need to try re-parse URL with `http://` prefix.
    url = new URL(server);
    if (!url.host || !url.protocol)
      url = new URL('http://' + server);
  } catch (e) {
    url = new URL('http://' + server);
  }
  if (url.protocol === 'socks4:' && (proxy.username || proxy.password))
    throw new Error(`Socks4 proxy protocol does not support authentication`);
  if (url.protocol === 'socks5:' && (proxy.username || proxy.password))
    throw new Error(`Browser does not support socks5 proxy authentication`);
  server = url.protocol + '//' + url.host;
  if (bypass)
    bypass = bypass.split(',').map(t => t.trim()).join(',');
  return { ...proxy, server, bypass };
}

const paramsThatAllowContextReuse: (keyof channels.BrowserNewContextForReuseParams)[] = [
  'colorScheme',
  'forcedColors',
  'reducedMotion',
  'contrast',
  'screen',
  'userAgent',
  'viewport',
  'testIdAttributeName',
];

const defaultNewContextParamValues: channels.BrowserNewContextForReuseParams = {

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. Drop username/password from the socks5 proxy config (use it only if the SOCKS5 endpoint requires no auth).
2. Use an HTTP/HTTPS proxy for authenticated proxying: proxy: { server: 'http://host:8080', username, password }.
3. Front the authenticated SOCKS5 server with a local unauthenticated relay (ssh -D, gost, etc.) and point Playwright at the local endpoint.

Example fix

// before
proxy: { server: 'socks5://proxy:1080', username: 'u', password: 'p' }
// after
proxy: { server: 'http://proxy:8080', username: 'u', password: 'p' }

function validateProxy(proxy?: { server: string; username?: string; password?: string }) {
  if (!proxy) return;
  const proto = new URL(proxy.server).protocol;
  if (proto === 'socks5:' && (proxy.username || proxy.password))
    throw new Error('Browsers do not support SOCKS5 auth; use an HTTP proxy or drop credentials');
}

function isAuthFreeSocks5(proxy: { server: string; username?: string; password?: string }): boolean {
  return new URL(proxy.server).protocol !== 'socks5:' || (!proxy.username && !proxy.password);
}

When it happens

Trigger: Launch/newContext with proxy: { server: 'socks5://host:1080', username: 'u', password: 'p' }.

Common situations: Trying to authenticate to a SOCKS5 proxy through the browser. Assuming Playwright resolves SOCKS5 auth the way it resolves HTTP proxy auth.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Socks4 proxy protocol does not support authentication
• ${path}: channels are not expected in SocksSupport
• ios_webkit_debug_proxy ${proxyBase}/json returned ${res.stat
• Invalid input image
• Invalid output dimensions

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/6ef2d54a09bc5dae. Report an issue: GitHub.