apify/crawlee · error · Error

A new page can be created with provided context only when us

Error message

A new page can be created with provided context only when using incognito pages.

What it means

Same rule as the Playwright controller: Puppeteer's _newPage can only honor per-page context options (like proxyServer) when each page gets its own incognito browser context. If contextOptions are passed but the launch context did not set useIncognitoPages: true, the shared-context setup cannot apply them, so it throws.

Source

Thrown at packages/browser-pool/src/puppeteer/puppeteer-controller.ts:45

            return {};
        }

        const url = new URL(proxyUrl);
        const username = decodeURIComponent(url.username);
        const password = decodeURIComponent(url.password);

        return {
            proxyServer: `${url.protocol}//${url.host}`,
            proxyUsername: username,
            proxyPassword: password,
            proxyBypassList: pageOptions?.proxyBypassList,
        };
    }

    protected async _newPage(contextOptions?: PuppeteerNewPageOptions): Promise<PuppeteerTypes.Page> {
        if (contextOptions !== undefined) {
            if (!this.launchContext.useIncognitoPages) {
                throw new Error('A new page can be created with provided context only when using incognito pages.');
            }

            let close = async () => {};
            if (contextOptions.proxyServer) {
                const [anonymizedProxyUrl, closeProxy] = await anonymizeProxySugar(
                    contextOptions.proxyServer,
                    contextOptions.proxyUsername,
                    contextOptions.proxyPassword,
                    { ignoreProxyCertificate: this.launchContext.ignoreProxyCertificate },
                );

                if (anonymizedProxyUrl) {
                    contextOptions.proxyServer = anonymizedProxyUrl;
                    delete contextOptions.proxyUsername;
                    delete contextOptions.proxyPassword;
                }

                close = closeProxy;

View on GitHub (pinned to dbe57fb09c)

Solutions

Set useIncognitoPages: true on the Puppeteer LaunchContext so per-page contextOptions (including proxyServer) are supported.
Drop the contextOptions argument and use a launch-time proxy instead (proxyUrl in LaunchContext).
Verify which plugin/mode is active before passing context options to newPage().

Example fix

// before
new PuppeteerPlugin(new LaunchContext({ puppeteer, ... })); // useIncognitoPages: false
await pool.newPage({ proxyServer: 'http://proxy:8080' }); // throws
// after
new PuppeteerPlugin(new LaunchContext({ puppeteer, useIncognitoPages: true, ... }));
await pool.newPage({ proxyServer: 'http://proxy:8080' }); // works

Defensive patterns

Strategy: validation

Validate before calling

function assertPuppeteerContextOptions(launchContext: { useIncognitoPages: boolean }, contextOptions?: PuppeteerNewPageOptions) {
  if (contextOptions !== undefined && !launchContext.useIncognitoPages) {
    throw new Error('Enable useIncognitoPages to pass contextOptions to newPage()');
  }
}

Type guard

function incognitoEnabled(lc: { useIncognitoPages?: boolean }): lc is { useIncognitoPages: true } {
  return lc.useIncognitoPages === true;
}

Try / catch

try {
  await pool.newPage({ proxyServer });
} catch (err) {
  if (err instanceof Error && err.message.includes('only when using incognito pages')) {
    // fallback: configure proxy via LaunchContext.proxyUrl instead
  } throw err;
}

Prevention

Set useIncognitoPages: true in the Puppeteer LaunchContext for per-page proxies.
For a single proxy, use LaunchContext's proxyUrl instead of per-page options.
Keep Puppeteer and Playwright launch configurations explicit and engine-specific.

When it happens

Trigger: Calling browserPool.newPage({ proxyServer: ... }) or any contextOptions against a PuppeteerPlugin whose LaunchContext has useIncognitoPages: false (default).

Common situations: Per-page proxy rotation attempts without incognito pages; reusing example code that passed proxyServer to newPage() in a default Puppeteer setup.

Related errors

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