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

PlaywrightController._newPage accepts optional context options, but those can only be applied when each page gets its own browser context — i.e. when the launch context was created with useIncognitoPages: true. Without incognito pages there is a single shared context, so passing contextOptions would silently misapply settings; the controller throws instead.

Source

Thrown at packages/browser-pool/src/playwright/playwright-controller.ts:36

        }

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

        return {
            proxy: {
                server: `${url.protocol}//${url.host}`,
                username,
                password,
                bypass: pageOptions?.proxy?.bypass,
            },
        };
    }

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

        let close = async () => {};

        if (this.launchContext.useIncognitoPages) {
            // Each page requires to have all the context options applied
            contextOptions = {
                ...this.launchContext.launchOptions,
                ...contextOptions,
            };

            // Remote browsers handle their own proxy — don't inject local proxy settings into context
            if (this.launchContext.isRemote) {
                delete contextOptions?.proxy;
            }

            if (contextOptions?.proxy) {
                const [anonymizedProxyUrl, closeProxy] = await anonymizeProxySugar(

View on GitHub (pinned to dbe57fb09c)

Solutions

Enable incognito pages: new PlaywrightPlugin(launchContext with useIncognitoPages: true), then pass contextOptions to newPage().
Remove the contextOptions argument and configure context-wide settings via launch options instead.
If isolation per page is needed, always use useIncognitoPages: true when constructing the plugin's LaunchContext.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

function assertContextOptionsUsable(launchContext: { useIncognitoPages: boolean }, contextOptions?: object) {
  if (contextOptions !== undefined && !launchContext.useIncognitoPages) {
    throw new Error('Pass contextOptions to newPage() only with useIncognitoPages: true');
  }
}

Type guard

function canPassContextOptions(o: { useIncognitoPages?: boolean } | undefined): o is { useIncognitoPages: true } {
  return o?.useIncognitoPages === true;
}

Try / catch

try {
  await pool.newPage(contextOptions);
} catch (err) {
  if (err instanceof Error && err.message.includes('only when using incognito pages')) {
    await pool.newPage(); // retry without options, configured at launch level
  } throw err;
}

Prevention

Always set useIncognitoPages: true when you plan to pass per-page contextOptions.
Configure proxies/UA at launch time (LaunchContext options) if not using incognito pages.
Add a startup assertion that flags contextOptions usage against the configured mode.

When it happens

Trigger: Calling browserPool.newPage({ ...contextOptions }) (or controller.newPage with options) while the PlaywrightPlugin was configured with useIncognitoPages: false (the default).

Common situations: Passing per-page proxyServer/contextOptions to newPage() in a default (non-incognito) setup; upgrading code that previously ignored contextOptions; copy-pasted incognito example code onto a default configuration.

Related errors

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