nodriver proxy with a username and password

Chrome won't read a login from --proxy-server, and nodriver doesn't raise when the page fails. Hand the login to create_context() or answer the proxy's challenge over CDP.

6 min readTested on nodriver 0.50.8 · zendriver 0.17.1 · Chrome 156
In nodriver a login inside --proxy-server fails with ERR_NO_SUPPORTED_PROXIES and the bare flag leaves a blank page; a Fetch.authRequired handler or create_context with proxy_server loads the page over HTTP and SOCKS5.Where the proxy login goes, and what the tab showsbrowser_args: --proxy-server=http://USER:PASS@…ERR_NO_SUPPORTED_PROXIESbrowser_args: --proxy-server=http://…:9000blank page+ Fetch.authRequired handler200 · DEcreate_context(proxy_server=http://USER:PASS@…)200 · DEcreate_context(proxy_server=socks5://USER:PASS@…)200 · DEnodriver 0.50.8 · zendriver 0.17.1 · Chrome 156 · November 5, 2026

In short

Don’t put USER:PASS@ into --proxy-server. Call browser.create_context(url, proxy_server="http://USER:PASS@host:port"), which also works for SOCKS5, or keep the bare flag and answer Fetch.authRequired once per request. Either way, check what the tab shows: nodriver doesn’t raise when the proxy fails.

create_context(proxy_server=…)Fetch.authRequired

nodriver starts a normal Chrome and talks to it over the DevTools protocol. A proxy goes into browser_args as --proxy-server, and that flag takes a scheme, a host and a port. Chrome rejects a value with a login in it, the same way it does for Puppeteer: ERR_NO_SUPPORTED_PROXIES.

The difference is how quietly it happens. await browser.get(url) returns a tab either way. With the login in the flag the tab holds Chrome’s error page; without it, the proxy answers 407, a headless Chrome has nobody to show the login prompt to, and the tab stays empty. A script that reads document.body.innerText gets an error text or an empty string and carries on.

We ran each variant with nodriver and zendriver against our gateway (HTTP on 9000, SOCKS5 on 11000), headless, loading ipinfo.io/json. Both libraries gave the same result in every row.

Where the proxy goesWhat the tab shows
--proxy-server=http://USER:PASS@…:9000error page, ERR_NO_SUPPORTED_PROXIES
--proxy-server=http://…:9000empty page (407 unanswered)
--proxy-server=http://…:9000 + Fetch handler200 · country DE
create_context(proxy_server="http://USER:PASS@…:9000")200 · country DE
create_context(proxy_server="socks5://USER:PASS@…:11000")200 · country DE
create_context(…) with a wrong passworderror page, ERR_TUNNEL_CONNECTION_FAILED
Fig. 1 — nodriver 0.50.8 and zendriver 0.17.1, Chrome 156.0.8078.81, headless, November 5, 2026. Login with -country-de.

A login in the flag

Chrome doesn’t read credentials out of --proxy-server and refuses the whole value. Every navigation shows the error page; no connection to the proxy is even tried.

The bare flag

Chrome connects, the proxy asks for a login, and nothing in the script answers it. In our headless runs the page simply never filled: an empty body, no error text, no exception.

The usual answer on GitHub is to enable the Fetch domain with handle_auth_requests=True and reply to every Fetch.authRequired with the login. That works while the login is right. With a wrong password, Chrome asks again and the handler answers again with the same wrong password:

hangsanswer every challenge · wrong password32 challenges in 25 s, tab.get() never returned
407answer once, then CancelAuth · wrong passworderror page HTTP ERROR 407, script continues
200answer once, then CancelAuth · right passwordone challenge per request

Remember which requests you already answered. A second challenge for the same request means the login was refused: cancel it. Then the tab shows a 407 page you can detect, instead of a script that hangs until something else times it out.

Two setups that work

Both ran unchanged with Python 3.12 against our gateway, with nodriver and, after changing the import, zendriver. PROXY_USER and PROXY_PASS come from the environment.

1. create_context() with the login

create_context() opens a new browser context and, when the proxy has a login, starts a small forwarder on 127.0.0.1 that adds it. Chrome gets the forwarder’s address without credentials. The nodriver docs mark the parameter as experimental; it worked for HTTP and SOCKS5 in our runs.

nodriver_context.py
import os

import nodriver as uc  # pip install nodriver

PROXY = f"http://{os.environ['PROXY_USER']}-country-de:{os.environ['PROXY_PASS']}@via.proxies.vision:9000"


async def main():
    browser = await uc.start(headless=True)
    try:
        # create_context() opens a new browser context behind a local forwarder
        # that adds the login, so Chrome itself never sees the credentials.
        tab = await browser.create_context("https://ipinfo.io/json", proxy_server=PROXY)
        await tab.sleep(2)
        print(await tab.evaluate("document.body.innerText"))
    finally:
        browser.stop()


uc.loop().run_until_complete(main())

2. The flag plus a Fetch handler that gives up

No forwarder: Chrome talks to the proxy itself and the handler supplies the login. HTTP proxies only, since Chrome can’t send a SOCKS5 login.

nodriver_cdp_auth.py
import os

import nodriver as uc  # pip install nodriver

USER = f"{os.environ['PROXY_USER']}-country-de"
PASS = os.environ["PROXY_PASS"]


async def main():
    # Only scheme, host and port go into the flag; Chrome rejects a login there.
    browser = await uc.start(headless=True, browser_args=["--proxy-server=http://via.proxies.vision:9000"])
    try:
        tab = browser.main_tab
        answered = set()

        async def on_auth(event: uc.cdp.fetch.AuthRequired):
            # Answer each request once. A second challenge means the login was
            # wrong: cancel instead of sending it again (Chrome asks forever).
            response = "CancelAuth" if event.request_id in answered else "ProvideCredentials"
            answered.add(event.request_id)
            await tab.send(uc.cdp.fetch.continue_with_auth(
                event.request_id,
                uc.cdp.fetch.AuthChallengeResponse(response, USER, PASS),
            ))

        async def on_paused(event: uc.cdp.fetch.RequestPaused):
            try:
                await tab.send(uc.cdp.fetch.continue_request(event.request_id))
            except uc.ProtocolException:
                pass  # a late request while the browser shuts down

        tab.add_handler(uc.cdp.fetch.AuthRequired, on_auth)
        tab.add_handler(uc.cdp.fetch.RequestPaused, on_paused)
        await tab.send(uc.cdp.fetch.enable(handle_auth_requests=True))

        await tab.get("https://ipinfo.io/json")
        await tab.sleep(2)
        print(await tab.evaluate("document.body.innerText"))
    finally:
        browser.stop()


uc.loop().run_until_complete(main())
txt
{
  "city": "Frankfurt am Main",
  "country": "DE",
  …

uc.loop().run_until_complete() instead of asyncio.run() is nodriver’s own recommendation; with asyncio.run() both scripts printed the page and then a RuntimeError: Event loop is closed from nodriver’s cleanup.

For zendriver, change the import to import zendriver as uc. In the second script, also write except uc.core.connection.ProtocolException: zendriver doesn’t export it at the top level. Targeting stays in the username: for one IP across pages add a session and use the sticky port, USER-country-de-session-job1-lifetime-10 on 10000. The same problem in Selenium.

How do I use a proxy with a username and password in nodriver?
Pass it to browser.create_context(url, proxy_server="http://USER:PASS@host:port"). nodriver starts a local forwarder that adds the login, so Chrome only sees a proxy without one. Or keep ‑‑proxy-server=http://host:port in browser_args and answer Fetch.authRequired over CDP.
Why does nodriver show a blank page or ERR_NO_SUPPORTED_PROXIES?
Chrome takes only scheme, host and port in ‑‑proxy-server. With a login inside the flag every page shows ERR_NO_SUPPORTED_PROXIES. Without the login, the proxy answers 407 and a headless tab stays blank, because nothing answers the login prompt. nodriver raises no exception in either case; check the page.
Does nodriver support SOCKS5 proxies with authentication?
Through create_context(), yes: socks5://USER:PASS@host:port loaded our test page, because the local forwarder speaks to the SOCKS5 proxy, not Chrome. Chrome itself can't send a SOCKS5 login, so the CDP handler only works with HTTP proxies.
Does the same code work with zendriver?
Yes. zendriver 0.17.1 is a fork with the same API: with import zendriver as uc both setups loaded the page. In the CDP script, catch uc.core.connection.ProtocolException, since zendriver doesn't export it at the top level.

Residential proxies, pay per GB

HTTP and SOCKS5. Country, city and sticky sessions in the username. No subscription.