FoundationAgents/MetaGPT · error · ValueError

Invalid scroll action {step}

Error message

Invalid scroll action {step}

What it means

MetaGPT's browser agent raises this in execute_action when a step classified as a scroll fails to match r'scroll ?\[?(up|down)\]?'. The parser only accepts 'scroll [up]', 'scroll [down]', or 'scroll up'/'scroll down' variants, so any other direction word or malformed text triggers the error.

Source

Thrown at metagpt/utils/a11y_tree.py:67

            match.group(1),
            match.group(2),
            match.group(3),
        )
        if enter_flag == "1":
            text += "\n"
        await click_element(page, get_backend_node_id(element_id, accessibility_tree))
        await type_text(page, text)
    elif func == "press":
        match = re.search(r"press ?\[(.+)\]", step)
        if not match:
            raise ValueError(f"Invalid press action {step}")
        key = match.group(1)
        await key_press(page, key)
    elif func == "scroll":
        # up or down
        match = re.search(r"scroll ?\[?(up|down)\]?", step)
        if not match:
            raise ValueError(f"Invalid scroll action {step}")
        direction = match.group(1)
        await scroll_page(page, direction)
    elif func == "goto":
        match = re.search(r"goto ?\[(.+)\]", step)
        if not match:
            raise ValueError(f"Invalid goto action {step}")
        url = match.group(1)
        await page.goto(url)
    elif func == "new_tab":
        page = await browser_ctx.new_page()
    elif func == "go_back":
        await page.go_back()
    elif func == "go_forward":
        await page.go_forward()
    elif func == "tab_focus":
        match = re.search(r"tab_focus ?\[(\d+)\]", step)
        if not match:
            raise ValueError(f"Invalid tab_focus action {step}")

View on GitHub (pinned to 11cdf466d0)

Solutions

  1. Normalize the step to 'scroll [up]' or 'scroll [down]' before calling execute_action.
  2. Log the offending step string to confirm what the LLM actually emitted.
  3. Update the action prompt to enumerate only scroll up/down as valid actions.
  4. Add a pre-check regex and retry the LLM call when it fails.

Example fix

# before
await execute_action(page, 'scroll [top]')  # raises Invalid scroll action

# after
await execute_action(page, 'scroll [up]')
Defensive patterns

Strategy: validation

Validate before calling

import re

def is_valid_scroll(step: str) -> bool:
    return bool(re.search(r"scroll ?\[?(up|down)\]?", step))

Try / catch

try:
    await execute_action(page, step)
except ValueError as e:
    if 'Invalid scroll action' in str(e):
        step = 'scroll [down]' if 'down' in step else 'scroll [up]'  # normalize and retry once

Prevention

When it happens

Trigger: execute_action(page, 'scroll [left]') or 'scroll [top]'); 'scroll upward' (only bare 'up'/'down' match); 'scroll[]' with empty direction; LLM emitting 'scroll to bottom' prose instead of the action syntax.

Common situations: LLM outputs horizontal scrolling or 'to top/bottom' phrasing that the strict up|down alternation rejects. Also happens when the step string gets truncated or has extra characters inside the brackets.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/9dc824b9d6f3f3fb. Report an issue: GitHub.