{"record":{"id":"7454ffbf07cdcf26","repo":"apify/crawlee","slug":"stagehand-extract-failed-improveerrormessage","errorCode":null,"errorMessage":"Stagehand extract() failed: ${improveErrorMessage(error)}","messagePattern":"Stagehand extract\\(\\) failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/stagehand-crawler/src/internals/utils/stagehand-utils.ts","lineNumber":91,"sourceCode":"            });\n        }\n    };\n\n    /**\n     * Extract structured data from the page using natural language and a Zod schema.\n     * Passes this specific page to Stagehand so it operates on the correct page.\n     */\n    enhancedPage.extract = async <T>(\n        instruction: string,\n        schema: ZodType<T>,\n        options?: Omit<ExtractOptions, 'page'>,\n    ): Promise<T> => {\n        try {\n            // Pass the page option to ensure Stagehand operates on this specific page\n            // Cast needed because Stagehand types reference older playwright-core versions\n            return await stagehand.extract(instruction, schema, { ...options, page: page as ExtractOptions['page'] });\n        } catch (error) {\n            throw new Error(`Stagehand extract() failed: ${improveErrorMessage(error)}`, {\n                cause: error,\n            });\n        }\n    };\n\n    /**\n     * Observe the page and get AI-suggested actions.\n     * Passes this specific page to Stagehand so it operates on the correct page.\n     */\n    enhancedPage.observe = async (options?: Omit<ObserveOptions, 'page'>) => {\n        try {\n            // Pass the page option to ensure Stagehand operates on this specific page\n            // Cast needed because Stagehand types reference older playwright-core versions\n            return await stagehand.observe({ ...options, page: page as ObserveOptions['page'] });\n        } catch (error) {\n            throw new Error(`Stagehand observe() failed: ${improveErrorMessage(error)}`, {\n                cause: error,\n            });","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/stagehand-crawler/src/internals/utils/stagehand-utils.ts#L73-L109","documentation":"enhancePageWithStagehand wraps Stagehand's extract() for structured data extraction on crawler pages. Any exception from stagehand.extract() (schema mismatch, LLM/API failure, page not ready, Stagehand internal error) is rethrown as 'Stagehand extract() failed: <improved message>' with the original error preserved as cause.","triggerScenarios":"Calling page.extract({ instruction, schema }) when the LLM call fails (missing/invalid API key, rate limits, timeouts), the schema cannot be satisfied by the page content, the page navigated or closed mid-extraction, or Stagehand's internal page mapping is stale.","commonSituations":"Zod schema fields the page cannot fill, missing OPENAI_API_KEY or wrong model name, extracting from pages that redirect immediately, and corporate proxies blocking the LLM API endpoint.","solutions":["Inspect the improved message / err.cause; fix auth (API key env vars) or model configuration if it's an LLM error","Loosen or correct the Zod schema (make optional fields optional) so extraction can succeed on real page content","Ensure the page is loaded and stable before extract() (wait for selector / networkidle)","Add retry with backoff for transient LLM/rate-limit failures","Verify network access to the LLM provider from the crawl environment"],"exampleFix":"// before\nconst data = await page.extract({ instruction: 'get the price', schema: z.object({ price: z.number() }) });\n// after\ntry {\n    const data = await page.extract({\n        instruction: 'Extract the product price from the page',\n        schema: z.object({ price: z.string().optional() }),\n    });\n} catch (err) {\n    log.warning('extract failed', err.cause ?? err);\n}","handlingStrategy":"try-catch","validationCode":"function canExtract(page, schema) {\n    return !page.isClosed?.() && typeof schema?.safeParse === 'function'\n        && !!(process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY);\n}","typeGuard":"const isExtractFailure = (e) => e instanceof Error && e.message.startsWith('Stagehand extract() failed:');","tryCatchPattern":"try {\n    const data = await page.extract({ instruction, schema });\n} catch (err) {\n    if (isExtractFailure(err)) {\n        log.warning('extract failed', err.cause ?? err);\n        return fallbackValue; // continue crawl without this record\n    }\n    throw err;\n}","preventionTips":["Make schema fields optional where page content may vary","Wait for page readiness before extracting","Retry transient LLM failures with backoff","Verify API keys and provider reachability in the crawl environment"],"tags":["stagehand","ai","extract","llm"],"backgroundTag":"stagehand-extraction-failed","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}