{"record":{"id":"e7478f6e9c6eb4d6","repo":"apify/crawlee","slug":"stagehand-agent-failed-improveerrormessage-er","errorCode":null,"errorMessage":"Stagehand agent() failed: ${improveErrorMessage(error)}","messagePattern":"Stagehand agent\\(\\) failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/stagehand-crawler/src/internals/utils/stagehand-utils.ts","lineNumber":128,"sourceCode":"        }\n    };\n\n    /**\n     * Create an autonomous agent for multi-step workflows.\n     * Note: Agent operates on the page context.\n     *\n     * The `as any` cast is needed because stagehand.agent() has two overloaded signatures\n     * (streaming vs non-streaming) that TypeScript struggles to reconcile when assigning\n     * to a property.\n     */\n    (enhancedPage as any).agent = (config?: AgentConfig) => {\n        try {\n            if (config?.stream === true) {\n                return stagehand.agent(config as AgentConfig & { stream: true });\n            }\n            return stagehand.agent(config as AgentConfig & { stream?: false });\n        } catch (error) {\n            throw new Error(`Stagehand agent() failed: ${improveErrorMessage(error)}`, {\n                cause: error,\n            });\n        }\n    };\n\n    return enhancedPage;\n}\n","sourceCodeStart":110,"sourceCodeEnd":136,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/stagehand-crawler/src/internals/utils/stagehand-utils.ts#L110-L136","documentation":"enhancePageWithStagehand wraps page.agent() so any synchronous error thrown while starting a Stagehand agent (e.g. invalid AgentConfig or SDK-level failure before streaming begins) is rethrown with a 'Stagehand agent() failed:' prefix and the original error as cause. Note it only covers the synchronous invocation; agent execution errors surface via the returned agent/promise.","triggerScenarios":"Calling enhancedPage.agent(config) where stagehand.agent() throws synchronously: malformed AgentConfig, unsupported stream option for the installed SDK version, model provider misconfiguration, or Stagehand instance already closed.","commonSituations":"Passing `stream: true` to a Stagehand version that lacks streaming agents, missing model API credentials, invalid model name in AgentConfig, constructing the agent on a closed Stagehand instance.","solutions":["Inspect `error.cause` for the root SDK error","Validate AgentConfig fields (model name, apiKey/env vars) before calling agent()","Check the installed stagehand SDK supports the streaming option you pass","Confirm the model provider credentials and account limits","Update the stagehand package to match the crawler's expected API"],"exampleFix":"// before\nconst agent = enhancedPage.agent({ model: 'gpt-4o', stream: true });\n\n// after\ntry {\n  const agent = enhancedPage.agent({ model: 'gpt-4o', stream: true });\n} catch (err) {\n  log.error('agent failed to start', { cause: err.cause });\n}","handlingStrategy":"try-catch","validationCode":"function validateAgentConfig(cfg: unknown): asserts cfg is AgentConfig {\n  if (typeof cfg !== 'object' || cfg === null) throw new TypeError('agent config must be an object');\n  if (!('model' in cfg)) throw new TypeError('agent config requires a model');\n}","typeGuard":"function isAgentConfig(v: unknown): v is AgentConfig {\n  return typeof v === 'object' && v !== null && typeof (v as any).model === 'string';\n}","tryCatchPattern":"try {\n  const agent = enhancedPage.agent(config);\n} catch (err) {\n  log.error('Stagehand agent failed to start', { cause: (err as Error).cause });\n}","preventionTips":["Validate AgentConfig shape and model name before calling agent()","Confirm the installed stagehand version supports the stream option you use","Check model credentials exist in the environment before runs","Never call agent() on a closed Stagehand instance"],"tags":["stagehand","llm","agent"],"backgroundTag":"stagehand-call-failed","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}