{"record":{"id":"80773f9876d36bab","repo":"apify/crawlee","slug":"could-not-resolve-stagehandcontroller-for-page-i","errorCode":null,"errorMessage":"Could not resolve StagehandController for page — is the browser pool configured correctly?","messagePattern":"Could not resolve StagehandController for page — is the browser pool configured correctly\\?","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/stagehand-crawler/src/internals/stagehand-crawler.ts","lineNumber":520,"sourceCode":"                this.browserPool as unknown as {\n                    getBrowserControllerByPage(page: StagehandPage): StagehandController | undefined;\n                }\n            ).getBrowserControllerByPage(page);\n        }\n\n        return undefined;\n    }\n\n    /**\n     * Enhance the page with Stagehand AI methods.\n     */\n    private async setUpStagehand(crawlingContext: {\n        page: Page;\n    }): Promise<{ stagehand: Stagehand; page: StagehandPage }> {\n        const controller = this.getBrowserControllerByPage(crawlingContext.page as StagehandPage);\n\n        if (!controller) {\n            throw new Error(\n                'Could not resolve StagehandController for page — is the browser pool configured correctly?',\n            );\n        }\n\n        const stagehand = controller.getStagehand();\n\n        return {\n            stagehand,\n            page: enhancePageWithStagehand(crawlingContext.page, stagehand),\n        };\n    }\n\n    /**\n     * Navigation handler for Stagehand crawler.\n     * Uses standard Playwright navigation.\n     */\n    protected override async navigationHandler(\n        crawlingContext: StagehandCrawlingContext,","sourceCodeStart":502,"sourceCodeEnd":538,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/stagehand-crawler/src/internals/stagehand-crawler.ts#L502-L538","documentation":"setUpStagehand() maps a crawling context's page back to its StagehandController via getBrowserControllerByPage() to fetch the Stagehand instance. When no controller is registered for that page, the crawler cannot proceed and throws this error hinting at a browser pool misconfiguration.","triggerScenarios":"Using a page inside requestHandler that did not originate from the Stagehand browser pool — e.g. a page created manually via playwright, pages created before the plugin registered controllers, or mixing StagehandCrawler with a custom browserPoolOptions browser plugin (default Playwright/Puppeteer plugin).","commonSituations":"Configuring browserPoolOptions with plain chromiumLauncherPlugin instead of StagehandPlugin, running pages through a different crawler instance, or passing foreign page objects to enhanced page utilities.","solutions":["Ensure the browser pool uses StagehandPlugin so pages get a StagehandController","Create all pages through the crawler/browser pool, never manually via playwright.chromium.launch()","Confirm you call enhancedPage helpers only on pages the same StagehandCrawler instance created","If using a custom page-generating plugin, wrap it so it delegates registration to StagehandController"],"exampleFix":"// before\nbrowserPoolOptions: { browserPlugins: [new PlaywrightPlugin(chromium.launchOptions)] }\n// after\nbrowserPoolOptions: { browserPlugins: [new StagehandPlugin()] }","handlingStrategy":"validation","validationCode":"const controller = crawler.getBrowserControllerByPage(page);\nif (!controller) {\n    throw new Error('page is not managed by the Stagehand browser pool; aborting stagehand setup');\n}","typeGuard":"const isPoolPage = (crawler, page) =>\n    typeof crawler.getBrowserControllerByPage === 'function' &&\n    crawler.getBrowserControllerByPage(page) != null;","tryCatchPattern":"try {\n    const { stagehand, page: spage } = await crawler.setUpStagehand(ctx);\n} catch (err) {\n    if (err.message.includes('Could not resolve StagehandController')) {\n        throw new Error('Configure browserPoolOptions.browserPlugins with StagehandPlugin');\n    }\n    throw err;\n}","preventionTips":["Only create pages through the crawler's browser pool","Use StagehandPlugin, not generic Playwright/Puppeteer plugins","Never mix pages from different crawler instances","Assert the pool configuration in an integration test"],"tags":["stagehand","browser-pool","configuration"],"backgroundTag":"browser-controller-not-resolved","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}