PuppeteerCrawlerOptions.launchContext.proxyUrl is not…

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.

Solutions

Move the URL into proxyConfiguration: new PuppeteerCrawler({ proxyConfiguration: await ProxyConfiguration.create({ proxyUrls: ['http://proxy:8080'] }) }).
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'] }),
});

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Configure proxies only through proxyConfiguration.
Grep codebase for 'launchContext' after upgrading crawlee.
Rely on TypeScript types to catch invalid option usage at build time.

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

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

Appendix: 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)