apify/crawlee · error

Stagehand act() failed: ${improveErrorMessage(error)}

Error message

Stagehand act() failed: ${improveErrorMessage(error)}

What it means

enhancePageWithStagehand wraps Stagehand's act() so crawler pages can drive AI actions. Any exception from stagehand.act() (element not found, LLM failure, timeout, Stagehand internal error) is rethrown as 'Stagehand act() failed: <improved message>' with the original attached as cause.

Source

Thrown at packages/stagehand-crawler/src/internals/utils/stagehand-utils.ts:71

 * ```
 *
 * @ignore
 */
export function enhancePageWithStagehand(page: Page, stagehand: Stagehand): StagehandPage {
    // Cast to StagehandPage to add properties
    const enhancedPage = page as StagehandPage;

    /**
     * Perform an action on the page using natural language.
     * Passes this specific page to Stagehand so it operates on the correct page.
     */
    enhancedPage.act = async (instruction: string, options?: Omit<ActOptions, 'page'>) => {
        try {
            // Pass the page option to ensure Stagehand operates on this specific page
            // Cast needed because Stagehand types reference older playwright-core versions
            return await stagehand.act(instruction, { ...options, page: page as ActOptions['page'] });
        } catch (error) {
            throw new Error(`Stagehand act() failed: ${improveErrorMessage(error)}`, {
                cause: error,
            });
        }
    };

    /**
     * Extract structured data from the page using natural language and a Zod schema.
     * Passes this specific page to Stagehand so it operates on the correct page.
     */
    enhancedPage.extract = async <T>(
        instruction: string,
        schema: ZodType<T>,
        options?: Omit<ExtractOptions, 'page'>,
    ): Promise<T> => {
        try {
            // Pass the page option to ensure Stagehand operates on this specific page
            // Cast needed because Stagehand types reference older playwright-core versions
            return await stagehand.extract(instruction, schema, { ...options, page: page as ExtractOptions['page'] });

View on GitHub (pinned to dbe57fb09c)

Solutions

1. Read the improved message and err.cause; if it's an auth error, set the correct API key env var for the configured model
2. Make act() instructions specific (target text/role) so Stagehand can resolve an element
3. Verify LLM provider connectivity and quota/rate limits
4. Re-check the page is open and idle before act(); retry once after a short delay on transient failures
5. Pin/upgrade @browserbasehq/stagehand if the cause points to an internal Stagehand bug

Example fix

// before
await page.act('click the thing');
// after
try {
    await page.act('Click the "Sign in" button in the header');
} catch (err) {
    log.warning('act failed', err.cause ?? err);
    await page.act('Click the button with text "Sign in"');
}

if (!process.env.OPENAI_API_KEY && !process.env.ANTHROPIC_API_KEY) {
    throw new Error('Set an LLM API key before calling page.act()');
}

const isActFailure = (e) => e instanceof Error && e.message.startsWith('Stagehand act() failed:');

try {
    await page.act('Click the "Add to cart" button');
} catch (err) {
    if (isActFailure(err)) log.warning('act failed', err.cause ?? err);
    // fall back to a plain Playwright click
    await page.click('text=Add to cart').catch(() => {});
}

When it happens

Trigger: Calling page.act('instruction') when Stagehand cannot complete the action: the instruction matched no element, the LLM/API call failed (invalid/missing API key, rate limit), the page navigated mid-action, or Stagehand's page reference went stale.

Common situations: Missing OPENAI_API_KEY / model credentials, vague act() instructions that match nothing, page closed or navigated between extract and act, network egress blocked to the LLM provider.

Related errors

• Stagehand extract() failed: ${improveErrorMessage(error)}
• Stagehand observe() failed: ${improveErrorMessage(error)}
• Stagehand agent() failed: ${improveErrorMessage(error)}
• Stagehand instance not found for browser
• No browser context available

AI-assisted analysis of apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/0b88e94b0813e331. Report an issue: GitHub.