{"record":{"id":"d74f8a7e4316cae7","repo":"apify/crawlee","slug":"a-new-page-can-be-created-with-provided-context-on","errorCode":null,"errorMessage":"A new page can be created with provided context only when using incognito pages.","messagePattern":"A new page can be created with provided context only when using incognito pages\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser-pool/src/playwright/playwright-controller.ts","lineNumber":36,"sourceCode":"        }\n\n        const url = new URL(proxyUrl);\n        const username = decodeURIComponent(url.username);\n        const password = decodeURIComponent(url.password);\n\n        return {\n            proxy: {\n                server: `${url.protocol}//${url.host}`,\n                username,\n                password,\n                bypass: pageOptions?.proxy?.bypass,\n            },\n        };\n    }\n\n    protected async _newPage(contextOptions?: SafeParameters<Browser['newPage']>[0]): Promise<Page> {\n        if (contextOptions !== undefined && !this.launchContext.useIncognitoPages) {\n            throw new Error('A new page can be created with provided context only when using incognito pages.');\n        }\n\n        let close = async () => {};\n\n        if (this.launchContext.useIncognitoPages) {\n            // Each page requires to have all the context options applied\n            contextOptions = {\n                ...this.launchContext.launchOptions,\n                ...contextOptions,\n            };\n\n            // Remote browsers handle their own proxy — don't inject local proxy settings into context\n            if (this.launchContext.isRemote) {\n                delete contextOptions?.proxy;\n            }\n\n            if (contextOptions?.proxy) {\n                const [anonymizedProxyUrl, closeProxy] = await anonymizeProxySugar(","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/browser-pool/src/playwright/playwright-controller.ts#L18-L54","documentation":"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.","triggerScenarios":"Calling browserPool.newPage({ ...contextOptions }) (or controller.newPage with options) while the PlaywrightPlugin was configured with useIncognitoPages: false (the default).","commonSituations":"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.","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."],"exampleFix":"// before\nnew PlaywrightPlugin(new LaunchContext({ ... })); // useIncognitoPages defaults to false\nawait pool.newPage({ proxyServer: 'http://proxy:8080' }); // throws\n// after\nnew PlaywrightPlugin(new LaunchContext({ ..., useIncognitoPages: true }));\nawait pool.newPage({ proxyServer: 'http://proxy:8080' }); // works","handlingStrategy":"validation","validationCode":"function assertContextOptionsUsable(launchContext: { useIncognitoPages: boolean }, contextOptions?: object) {\n  if (contextOptions !== undefined && !launchContext.useIncognitoPages) {\n    throw new Error('Pass contextOptions to newPage() only with useIncognitoPages: true');\n  }\n}","typeGuard":"function canPassContextOptions(o: { useIncognitoPages?: boolean } | undefined): o is { useIncognitoPages: true } {\n  return o?.useIncognitoPages === true;\n}","tryCatchPattern":"try {\n  await pool.newPage(contextOptions);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('only when using incognito pages')) {\n    await pool.newPage(); // retry without options, configured at launch level\n  } throw err;\n}","preventionTips":["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."],"tags":["browser-pool","playwright","incognito","context-options"],"backgroundTag":"api-requires-option-enabled","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}