apify/crawlee · error

PuppeteerCrawlerOptions.launchContext.proxyUrl is not allowe

Error message

PuppeteerCrawlerOptions.launchContext.proxyUrl is not allowed in PuppeteerCrawler.Use PuppeteerCrawlerOptions.proxyConfiguration

What it means

PuppeteerCrawler mirrors PlaywrightCrawler: per-crawler proxy must be set through proxyConfiguration (a ProxyConfiguration instance), not launchContext.proxyUrl. The constructor validates parsed options and throws this error for the legacy option so misconfiguration fails fast instead of silently running without a proxy.

Source

Thrown at packages/puppeteer-crawler/src/internals/puppeteer-crawler.ts:230

    /**
     * All `PuppeteerCrawler` parameters are passed via an options object.
     */
    constructor(
        options: PuppeteerCrawlerOptions<ContextExtension, ExtendedContext, Routes, StatisticStateExtension> = {},
    ) {
        const parsedOptions = parseArgument(options, PuppeteerCrawler.optionsSchema, 'PuppeteerCrawlerOptions');

        const {
            launchContext,
            headless,
            configuration,
            proxyConfiguration,
            contextPipelineBuilder,
            ...browserCrawlerOptions
        } = parsedOptions;

        if (launchContext.proxyUrl) {
            throw new Error(
                'PuppeteerCrawlerOptions.launchContext.proxyUrl is not allowed in PuppeteerCrawler.' +
                    'Use PuppeteerCrawlerOptions.proxyConfiguration',
            );
        }

        if (options.browserPool) {
            // The raw options, not the parsed ones: `launchContext` has a default, so by now it is always set.
            assertBrowserPoolNotConfigured(new.target.name, {
                launchContext: options.launchContext,
                headless: options.headless,
            });
        }

        super({
            ...(browserCrawlerOptions as BrowserCrawlerOptions<
                Page,
                HTTPResponse,
                PuppeteerCrawlingContext,

View on GitHub (pinned to dbe57fb09c)

Solutions

1. Move the URL into proxyConfiguration: new PuppeteerCrawler({ proxyConfiguration: await ProxyConfiguration.create({ proxyUrls: ['http://proxy:8080'] }) }).
2. Keep other launch options (args, executablePath) in launchContext — only proxyUrl is rejected.

Example fix

// before
const crawler = new PuppeteerCrawler({
    launchContext: { proxyUrl: 'http://proxy.example.com:8080' },
});
// after
const crawler = new PuppeteerCrawler({
    proxyConfiguration: await ProxyConfiguration.create({ proxyUrls: ['http://proxy.example.com:8080'] }),
});

function assertNoLaunchProxy(options: PuppeteerCrawlerOptions) {
    if ((options as any)?.launchContext?.proxyUrl) {
        throw new Error('Use proxyConfiguration instead of launchContext.proxyUrl');
    }
}

When it happens

Trigger: new PuppeteerCrawler({ launchContext: { proxyUrl: 'http://proxy:8080' } }).

Common situations: Upgrading from older Crawlee versions where launchContext.proxyUrl was supported; porting Playwright proxy snippets; outdated documentation or examples.

Related errors

• PlaywrightCrawlerOptions.launchContext.proxyUrl is not allow
• Invalid "proxyUrl". Unsupported protocol: ${proxyUrl}.
• A new page can be created with provided context only when us
• The `tieredProxyUrls` option has been removed in Crawlee v4.
• The provided newUrlFunction did not return a valid URL. Caus

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