Autenticación de Proxy SOCKS5 en Playwright: Por qué Falla, 4 Soluciones

Playwright acepta un servidor socks5:// y luego rechaza tu nombre de usuario y contraseña. La limitación es de Chromium, no de Playwright, y ha estado abierta desde 2021 — aquí están las cuatro formas de solucionarlo, clasificadas.

La autenticación de proxy SOCKS5 en Playwright no existe, y saberlo de antemano te ahorra una noche. Pasas un servidor socks5:// junto con un nombre de usuario y contraseña y Playwright lo rechaza antes de que el navegador navegue. La solicitud de función en la que todos terminan, microsoft/playwright#10567, se abrió en noviembre de 2021, sigue abierta y aún lleva la etiqueta P3-collecting-feedback. La limitación no es de Playwright para solucionar: reside en Chromium. Esta publicación muestra las cadenas de error exactas, explica por qué ninguna extensión o bandera de configuración te rescata, y ofrece cuatro soluciones — el intercambio HTTP de una línea, la lista blanca de IP, un relé local y Firefox.

El error que estás buscando

Cada versión de este problema produce una de dos cadenas. En Node obtienes Error: Browser does not support socks5 proxy authentication; en Python, las versiones anteriores lo prefijan con playwright._impl._api_types.Error: y las más recientes con playwright._impl._errors.Error:. El mensaje es el mismo, y se lanza al inicio, no durante la navegación:

const { chromium } = require('playwright');

// Fails immediately — no page is ever created
const browser = await chromium.launch({
  proxy: {
    server: 'socks5://gate.quantumproxies.io:PORT',
    username: 'USER',
    password: 'PASS',
  },
});
// Error: Browser does not support socks5 proxy authentication

// Python raises the same thing:
// playwright._impl._errors.Error: Browser does not support
// socks5 proxy authentication

Hay una variante más silenciosa. Si omites los campos de credenciales y los incluyes en la cadena del servidor — socks5://USER:PASS@host:1080 — no se lanza nada. Chromium simplemente ignora la parte de información de usuario de la URL, intenta un handshake no autenticado, y la puerta de enlace lo rechaza. Luego ves net::ERR_SOCKS_CONNECTION_FAILED o un simple tiempo de espera en el primer goto(), lo que lleva a las personas a buscar errores de red que no existen.

Dónde realmente falla la autenticación de proxy SOCKS5 en Playwright

La propia documentación de Playwright es explícita: los campos username y password en la opción de proxy se describen como credenciales para usar "si el proxy HTTP requiere autenticación". SOCKS solo se admite como un esquema. En el fondo, Chromium nunca implementó la subnegociación de nombre de usuario/contraseña del RFC 1929 para SOCKS5, por lo que la entrada en el rastreador de problemas de Chromium sobre la autenticación SOCKS5 (40323993) ha recopilado años de comentarios, por qué la extensión SwitchyOmega advierte a los usuarios en el momento en que seleccionan SOCKS5 con credenciales, y por qué Brave y Edge se comportan de manera idéntica. Es un motor, una brecha, heredada por todo lo construido sobre él.

Esto también es por lo que el truco que rescata a los usuarios de Selenium no ayuda aquí. Una extensión de Manifest V3 puede responder a un desafío de proxy a través de chrome.webRequest.onAuthRequired, pero ese gancho se activa en respuestas HTTP 407 Proxy Authentication Required. Un handshake SOCKS5 es una negociación a nivel de bytes en el socket antes de que exista cualquier HTTP, por lo que no hay evento para interceptar. Y no confundas la opción de contexto httpCredentials con la autenticación de proxy: responde a desafíos 401 del sitio web que estás visitando, nunca del proxy. Para una visión completa a través de los marcos de sigilo, nuestro mapa de proxies autenticados en marcos anti-detección cubre quién soporta qué.

Solución 1: usar el endpoint HTTP de la misma puerta de enlace

Esta es la solución para aproximadamente nueve de cada diez usuarios, y es una línea. Los proveedores serios exponen el mismo grupo de IP en ambos protocolos en diferentes puertos — cada plan de QuantumProxies incluye endpoints HTTP y SOCKS5 con las mismas credenciales y la misma sintaxis de sesión. Cambia el esquema y el puerto, mantén todo lo demás, y los campos de credenciales nativos de Playwright hacen su trabajo:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        # was: "socks5://gate.quantumproxies.io:SOCKS_PORT"
        "server": "http://gate.quantumproxies.io:PORT",
        "username": "USER",
        "password": "PASS",
    })
    page = browser.new_page()
    page.goto("https://httpbin.org/ip")
    print(page.text_content("body"))   # must be the proxy exit IP
    browser.close()

No pierdes nada medible. Para el tráfico de navegador, un proxy HTTP abre un túnel CONNECT y transporta los mismos bytes encriptados que lo haría un túnel SOCKS5; las diferencias entre los dos protocolos importan para el tráfico UDP y no HTTP, no para la carga de una página. Nuestro desglose de SOCKS5 versus proxies HTTP tiene el detalle. Y dado que el objeto proxy también es aceptado por newContext(), las mismas credenciales te dan rotación por contexto exactamente como se describe en nuestra guía de integración de proxy en Playwright.

Solución 2: la lista blanca de IP mantiene vivo socks5://

Si realmente necesitas el esquema SOCKS5 — un proxy que solo habla SOCKS, una cadena de herramientas que lo asume — autentica la máquina en lugar de la solicitud. Registra la IP pública del scraper con tu proveedor, elimina las credenciales, y Chromium está feliz porque no hay nada que negociar:

const { chromium } = require('playwright');

const browser = await chromium.launch({
  proxy: { server: 'socks5://gate.quantumproxies.io:PORT' }, // no creds
});
const page = await browser.newPage();
await page.goto('https://httpbin.org/ip');
console.log(await page.textContent('body'));
await browser.close();

La lista blanca autentica una máquina, no un script, y ese es todo el intercambio. Un VPS o una salida de oficina con una dirección estable funciona perfectamente; los runners de CI efímeros, los contenedores autoescalados y cualquier cosa detrás de un NAT rotativo fallarán en el momento en que cambie la dirección. Verifica la salida antes de confiar en una ejecución — una conexión directa silenciosa se ve exactamente como un proxy funcionando hasta que tu objetivo comienza a bloquear tu propia IP. Nuestro verificador de calidad de IP gratuito te dice cuál es realmente la salida, no solo que respondió.

Comparación de cuatro soluciones para la autenticación de proxy SOCKS5 en Playwright: endpoint HTTP, lista blanca de IP, relé local y Firefox — El intercambio de endpoint HTTP cuesta una línea y ninguna capacidad. Todo a la derecha de esto te compra el esquema socks5:// a un precio.

Solución 3: un relé local que elimina las credenciales

Cuando la IP no puede ser incluida en la lista blanca y el proveedor no tiene puerto HTTP, coloca un traductor frente al navegador. El patrón es siempre el mismo: un oyente local sin autenticación reenvía al endpoint SOCKS5 upstream con credenciales adjuntas. Con gost, eso es un solo comando:

# Local no-auth HTTP listener -> authenticated upstream SOCKS5
gost -L=http://127.0.0.1:8080 \
     -F=socks5://USER:PASS@gate.quantumproxies.io:PORT

# Playwright then points at the local hop, with no credentials:
#   proxy: { server: 'http://127.0.0.1:8080' }

Dos reglas. Vincula el oyente a 127.0.0.1, nunca a 0.0.0.0 — un proxy sin autenticación accesible desde internet es un relé abierto que será encontrado y abusado en cuestión de horas. Y trata el relé como un proceso que debes supervisar: si muere, Chromium vuelve a un error de conexión en lugar de una solicitud directa, lo cual al menos es ruidoso. Este enfoque se ha vuelto lo suficientemente común como para que los practicantes publiquen pequeños relés construidos para este propósito; comparamos las opciones en nuestra guía de herramientas de relé de autenticación SOCKS5.

Solución 4: ejecutar Firefox en lugar de Chromium

Firefox implementa la autenticación de nombre de usuario/contraseña SOCKS5 de forma nativa, que es la diferencia a la que sigue apuntando el hilo de problemas de Playwright. Cambia el tipo de navegador y el error desaparece:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.firefox.launch(proxy={
        "server": "socks5://gate.quantumproxies.io:PORT",
        "username": "USER",
        "password": "PASS",
    })
    page = browser.new_page()
    page.goto("https://httpbin.org/ip")
    print(page.text_content("body"))   # confirm the exit before trusting it
    browser.close()

Haz el paso de verificación, cada vez. Que Playwright no lance un error no es prueba de que se usaron las credenciales — solo un eco de IP lo es. Y sé claro sobre lo que estás comprando: un motor de renderizado diferente, una superficie de huella digital diferente, y un ecosistema de sigilo que se inclina fuertemente hacia Chromium. Si tu objetivo ya acepta Firefox, esto es gratis. Si elegiste Chromium por razones anti-bot, cambiar de motor para resolver un problema de proxy es el intercambio equivocado — toma la solución 1 y mantén tu navegador.

La decisión, en una línea cada una

El proveedor tiene un puerto HTTP: úsalo. Una línea, autenticación nativa, mismas salidas, sin proceso extra.
IP pública fija: inclúyela en la lista blanca y mantén socks5:// sin credenciales.
Ninguna: ejecuta un relé local vinculado al loopback y apunta Playwright a 127.0.0.1.
Ya en Firefox: pasa las credenciales y verifica la IP de salida una vez.
Nunca: credenciales dentro de la cadena server. Chromium las descarta sin decir nada.

Lista de verificación de configuraciones de proxy SOCKS5 en Playwright que funcionan en Chromium versus configuraciones que lanzan errores o fallan silenciosamente — Chromium acepta el esquema SOCKS5 y nunca las credenciales. Todo a la derecha de esta lista falla — la mitad sin un error.

Preguntas frecuentes

¿Playwright soporta la autenticación de proxy SOCKS5?

No con Chromium. La opción de proxy de Playwright documenta el nombre de usuario y la contraseña como credenciales HTTP(S), y Chromium no tiene implementación de nombre de usuario/contraseña SOCKS5 para entregarlas, por lo que el lanzamiento falla. Firefox en Playwright sí lo soporta. El problema de seguimiento, microsoft/playwright#10567, ha estado abierto desde noviembre de 2021 sin solución programada.

¿Qué significa 'Browser does not support socks5 proxy authentication'?

Significa que pasaste credenciales junto a un servidor socks5:// a un lanzamiento de Chromium. Playwright valida la combinación y la rechaza en lugar de abrir un navegador que las ignoraría silenciosamente. O muévete al puerto HTTP de la puerta de enlace y mantén los campos de credenciales, o autentica por lista blanca de IP y elimínalos por completo.

¿Cómo uso un proxy SOCKS5 con Playwright en Python?

Pasa proxy={"server": "socks5://host:port"} sin nombre de usuario ni contraseña, y haz que el proveedor autorice la IP pública de tu máquina. Si la IP no es estable, usa el endpoint HTTP de la misma puerta de enlace con credenciales, o reenvía a través de un relé local. Siempre confirma la salida contra un endpoint de eco de IP.

¿Puede una extensión de Chrome agregar autenticación SOCKS5?

No. El truco de la extensión usado para proxies HTTP autenticados se basa en chrome.webRequest.onAuthRequired, que se activa en respuestas HTTP 407. SOCKS5 autentica durante el handshake del socket, antes de que exista cualquier solicitud HTTP, por lo que ninguna API de extensión puede verlo. Las extensiones de cambio de proxy advierten sobre esta limitación por la misma razón.

¿Es SOCKS5 más rápido que HTTP para scraping con Playwright?

No de manera significativa. El tráfico HTTPS a través de un proxy HTTP usa un túnel CONNECT, por lo que ambos protocolos transportan el mismo flujo encriptado con una sobrecarga comparable. Las verdaderas ventajas de SOCKS5 son el soporte UDP y la neutralidad de protocolo, ninguna de las cuales usa la carga de una página de navegador. Elige el endpoint que autentique limpiamente.

La versión corta: deja de intentar que Chromium haga algo que nunca ha hecho. Mueve el trabajo al endpoint HTTP, o incluye en la lista blanca y elimina las credenciales — y si debes mantener socks5:// con una salida rotativa, coloca un relé en el medio en lugar de una solución alternativa en tu código. Una vez que la autenticación está fuera del camino, lo que decide si la ejecución tiene éxito es el pool detrás de ella: salidas residenciales en más de 200 países, con rotación por solicitud o sesiones pegajosas cuando un flujo necesita una identidad.

Obtén endpoints HTTP y SOCKS5 en un solo plan