FoundationAgents/MetaGPT · error · ValueError

Invalid hover action {step}

Error message

Invalid hover action {step}

What it means

ValueError from execute_step: the step starts with 'hover' but fails the regex `hover ?\[(\d+)\]`, i.e. the bracketed element id is missing, non-numeric, or malformed. Same grammar contract as click: the numeric id must reference a nodeId present in the accessibility tree.

Source

Thrown at metagpt/utils/a11y_tree.py:37

            seen_ids.add(node["nodeId"])
    return accessibility_tree


async def execute_step(step: str, page: Page, browser_ctx: BrowserContext, accessibility_tree: list):
    step = step.strip()
    func = step.split("[")[0].strip() if "[" in step else step.split()[0].strip()
    if func == "None":
        return ""
    elif func == "click":
        match = re.search(r"click ?\[(\d+)\]", step)
        if not match:
            raise ValueError(f"Invalid click action {step}")
        element_id = match.group(1)
        await click_element(page, get_backend_node_id(element_id, accessibility_tree))
    elif func == "hover":
        match = re.search(r"hover ?\[(\d+)\]", step)
        if not match:
            raise ValueError(f"Invalid hover action {step}")
        element_id = match.group(1)
        await hover_element(page, get_backend_node_id(element_id, accessibility_tree))
    elif func == "type":
        # add default enter flag
        if not (step.endswith("[0]") or step.endswith("[1]")):
            step += " [1]"

        match = re.search(r"type ?\[(\d+)\] ?\[(.+)\] ?\[(\d+)\]", step)
        if not match:
            raise ValueError(f"Invalid type action {step}")
        element_id, text, enter_flag = (
            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))

View on GitHub (pinned to 11cdf466d0)

Solutions

1. Format the step as `hover [N]` with N a numeric nodeId from the accessibility tree
2. Pre-validate with re.search(r'hover ?\[(\d+)\]', step) before calling execute_step
3. Include concrete hover examples in the agent's action-space prompt

Example fix

# before
await execute_step("hover [nav menu]", page, ctx, tree)  # ValueError
# after
await execute_step("hover [7]", page, ctx, tree)  # 7 = nodeId from a11y tree

import re
if not re.search(r"hover ?\[(\d+)\]", step):
    raise SystemExit(f"malformed hover step: {step!r}; expected 'hover [id]'")

def is_valid_hover(step: str) -> bool:
    import re
    return bool(re.fullmatch(r"hover ?\[\d+\]", step.strip()))

try:
    await execute_step(step, page, ctx, tree)
except ValueError:
    step = f"hover [{node_id}]"
    await execute_step(step, page, ctx, tree)

When it happens

Trigger: Steps like 'hover [menu]', 'hover[3' , 'hover' with no argument, or a step whose id is a name rather than a nodeId.

Common situations: Agent outputs semantic element names instead of numeric node ids; truncated step strings from token limits; prompts that never show the hover grammar.

Related errors

• Invalid click action {step}
• Invalid type action {step}
• Only support for python, markdown, but got {language}
• Only support for language: python, markdown, but got {langua
• The invoice format is not zip, pdf, png, or jpg

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