What causes "Invalid "proxyUrl". Unsupported protocol: ${proxyUrl}." in apify/crawlee?

Prefix the proxy URL with a supported scheme: `http://host:port` (most common) or `socks5://host:port`

apify/crawlee · error · Error

Invalid "proxyUrl". Unsupported protocol: ${proxyUrl}.

Error message

Invalid "proxyUrl". Unsupported protocol: ${proxyUrl}.

What it means

`BrowserLauncher.validateProxyUrlProtocol()` validates the `proxyUrl` option before launching the browser. The URL must start with a supported scheme — http, https, socks4, or socks5 (case-insensitive). Anything else (ftp://, missing scheme, typos like `localhost:8080` with no scheme) is rejected with this error at construction time, failing fast instead of producing a broken browser launch.

Source

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

                chromeExecutablePath = path86;
            }
            return chromeExecutablePath;
        };
        switch (os.platform()) {
            case 'darwin':
                return '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
            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

Prefix the proxy URL with a supported scheme: `http://host:port` (most common) or `socks5://host:port`
Use `socks4://` or `socks5://` explicitly instead of bare `socks://`
If credentials are needed, keep the http/https scheme: `http://user:pass@host:port`
Validate the env/config value before constructing the crawler

Example fix

// before
new PlaywrightCrawler({ launchContext: { proxyUrl: 'my-proxy.example.com:8080' } });
// after
new PlaywrightCrawler({ launchContext: { proxyUrl: 'http://my-proxy.example.com:8080' } });

Defensive patterns

Strategy: validation

Validate before calling

function assertValidProxyUrl(proxyUrl?: string): void {
    if (!proxyUrl) return;
    if (!/^(http|https|socks4|socks5)/i.test(proxyUrl)) {
        throw new Error(`proxyUrl must start with http(s)/socks4/socks5, got: ${proxyUrl}`);
    }
    new URL(proxyUrl); // throws on malformed URLs
}

Try / catch

try {
    const crawler = new PlaywrightCrawler({ launchContext: { proxyUrl } });
} catch (e) {
    if (e instanceof Error && /Unsupported protocol/.test(e.message)) {
        log.error(`Fix proxyUrl scheme: ${e.message}`);
        process.exit(1);
    }
    throw e;
}

Prevention

Always include an explicit scheme (http:// or socks5://) in proxy URLs
Watch for providers giving scheme-less host:port strings — prefix them yourself
Never use bare socks:// — write socks4:// or socks5://

When it happens

Trigger: Passing `proxyUrl: 'ftp://...'`, `'myproxy.com:8080'` (no scheme), `'socks://...'` (generic socks, not socks4/socks5), or an empty-string-prefixed garbage value into `BrowserLauncher`/crawler options; also triggered via `new URL()` paths if the regex passes but the value is malformed.

Common situations: Copying a proxy host from a provider dashboard that omits the scheme; using `socks://` because the provider labels it just "SOCKS"; accidentally pasting a full provider URL that begins with a scheme the launcher doesn't accept; environment variables containing scheme-less proxy addresses.

Related errors

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