apify/crawlee · error · Error

Invalid "proxyUrl" option: authentication is only supported

Error message

Invalid "proxyUrl" option: authentication is only supported for HTTP proxy type.

What it means

The second check in `validateProxyUrlProtocol()`: if the `proxyUrl` embeds credentials (`url.username` or `url.password`), the scheme must be `http:` or `https:`. Browsers' proxy settings (and Chromium's `--proxy-server` flag) do not support inline authentication for SOCKS proxies, so a `socks5://user:pass@host:port` value is rejected with this explicit message rather than failing mysteriously at connect time.

Source

Thrown at packages/browser-crawler/src/internals/browser-launcher.ts:339

            case 'win32':
                return getWin32Path();
            default:
                return '/usr/bin/google-chrome';
        }
    }

    private validateProxyUrlProtocol(proxyUrl?: string): void {
        if (!proxyUrl) return;

        if (!/^(http|https|socks4|socks5)/i.test(proxyUrl)) {
            throw new Error(`Invalid "proxyUrl". Unsupported protocol: ${proxyUrl}.`);
        }

        const url = new URL(proxyUrl);

        if (url.username || url.password) {
            if (url.protocol !== 'http:' && url.protocol !== 'https:') {
                throw new Error('Invalid "proxyUrl" option: authentication is only supported for HTTP proxy type.');
            }
        }
    }
}

View on GitHub (pinned to dbe57fb09c)

Solutions

Switch to an HTTP/HTTPS proxy endpoint from your provider so inline credentials (`http://user:pass@host:port`) work
Remove credentials from the SOCKS URL and authenticate at the network level (IP allowlisting the crawler's IP at the proxy provider)
Handle SOCKS auth out-of-band (e.g. a local forwarder like `gost`/`3proxy` that adds the credentials, then point proxyUrl at it)
Ask the provider for an authenticated HTTP tunnel or an IP-whitelisted SOCKS endpoint

Example fix

// before
proxyUrl: 'socks5://user:pass@proxy.example.com:1080' // throws
// after
proxyUrl: 'http://user:pass@proxy.example.com:8080' // HTTP proxy with inline auth, supported

Defensive patterns

Strategy: validation

Validate before calling

function assertProxyAuthSupported(proxyUrl?: string): void {
    if (!proxyUrl) return;
    const url = new URL(proxyUrl);
    if ((url.username || url.password) && !['http:', 'https:'].includes(url.protocol)) {
        throw new Error(`Inline credentials are only supported for http/https proxies, got ${url.protocol}`);
    }
}

Try / catch

try {
    const launcher = new BrowserLauncher({ proxyUrl });
} catch (e) {
    if (e instanceof Error && /authentication is only supported for HTTP proxy/.test(e.message)) {
        log.error('Move credentials out of the SOCKS URL: use IP allowlisting or an HTTP proxy endpoint');
    }
    throw e;
}

Prevention

Strip user:pass from SOCKS URLs and use provider IP allowlisting instead
Prefer HTTP proxy endpoints when inline credentials are required
Keep a config-level validator that mirrors the launcher's scheme+auth rules before deployment

When it happens

Trigger: Constructing the launcher/crawler with a `proxyUrl` such as `socks5://user:pass@host:1080` — a SOCKS4/SOCKS5 proxy URL that includes username/password in the URL.

Common situations: Proxy providers issue SOCKS credentials and developers paste them straight into the URL; migrating a proxy string from an HTTP proxy (where inline auth works) to a SOCKS proxy without removing the credentials; assuming SOCKS5 RFC 1929 auth maps to URL credentials.

Understand the failure class

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

Related errors

AI-assisted analysis of apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/5421b4ccbbd58634. Report an issue: GitHub.