{"record":{"id":"e93eb21cf48ab68d","repo":"apify/crawlee","slug":"a-new-page-can-be-created-with-provided-context-on-e93eb2","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/puppeteer/puppeteer-controller.ts","lineNumber":45,"sourceCode":"            return {};\n        }\n\n        const url = new URL(proxyUrl);\n        const username = decodeURIComponent(url.username);\n        const password = decodeURIComponent(url.password);\n\n        return {\n            proxyServer: `${url.protocol}//${url.host}`,\n            proxyUsername: username,\n            proxyPassword: password,\n            proxyBypassList: pageOptions?.proxyBypassList,\n        };\n    }\n\n    protected async _newPage(contextOptions?: PuppeteerNewPageOptions): Promise<PuppeteerTypes.Page> {\n        if (contextOptions !== undefined) {\n            if (!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            if (contextOptions.proxyServer) {\n                const [anonymizedProxyUrl, closeProxy] = await anonymizeProxySugar(\n                    contextOptions.proxyServer,\n                    contextOptions.proxyUsername,\n                    contextOptions.proxyPassword,\n                    { ignoreProxyCertificate: this.launchContext.ignoreProxyCertificate },\n                );\n\n                if (anonymizedProxyUrl) {\n                    contextOptions.proxyServer = anonymizedProxyUrl;\n                    delete contextOptions.proxyUsername;\n                    delete contextOptions.proxyPassword;\n                }\n\n                close = closeProxy;","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/browser-pool/src/puppeteer/puppeteer-controller.ts#L27-L63","documentation":"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.","triggerScenarios":"Calling browserPool.newPage({ proxyServer: ... }) or any contextOptions against a PuppeteerPlugin whose LaunchContext has useIncognitoPages: false (default).","commonSituations":"Per-page proxy rotation attempts without incognito pages; reusing example code that passed proxyServer to newPage() in a default Puppeteer setup.","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()."],"exampleFix":"// before\nnew PuppeteerPlugin(new LaunchContext({ puppeteer, ... })); // useIncognitoPages: false\nawait pool.newPage({ proxyServer: 'http://proxy:8080' }); // throws\n// after\nnew PuppeteerPlugin(new LaunchContext({ puppeteer, useIncognitoPages: true, ... }));\nawait pool.newPage({ proxyServer: 'http://proxy:8080' }); // works","handlingStrategy":"validation","validationCode":"function assertPuppeteerContextOptions(launchContext: { useIncognitoPages: boolean }, contextOptions?: PuppeteerNewPageOptions) {\n  if (contextOptions !== undefined && !launchContext.useIncognitoPages) {\n    throw new Error('Enable useIncognitoPages to pass contextOptions to newPage()');\n  }\n}","typeGuard":"function incognitoEnabled(lc: { useIncognitoPages?: boolean }): lc is { useIncognitoPages: true } {\n  return lc.useIncognitoPages === true;\n}","tryCatchPattern":"try {\n  await pool.newPage({ proxyServer });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('only when using incognito pages')) {\n    // fallback: configure proxy via LaunchContext.proxyUrl instead\n  } throw err;\n}","preventionTips":["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."],"tags":["browser-pool","puppeteer","incognito","proxy"],"backgroundTag":"api-requires-option-enabled","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}