stablyai/orca · error · RuntimeError

unknown tool: {tool}

Error message

unknown tool: {tool}

What it means

Raised in run_operation (runtime.py:1124) as the final else of the tool dispatch chain — the operation['tool'] value did not match any known tool (handshake, list_apps, list_windows, get_app_state, click, perform_secondary_action, scroll, drag, type_text, press_key, hotkey, paste_text, set_value). It indicates an unrecognized or misspelled tool name in the request.

Source

Thrown at native/computer-use-linux/runtime.py:1124

        action = {"path": "synthetic", "actionName": "drag", "fallbackReason": None}
    elif tool == "type_text":
        type_text(require_non_empty_string(operation.get("text"), "text"))
        action = {"path": "synthetic", "actionName": "typeText", "fallbackReason": None, "verification": {"state": "unverified", "reason": "synthetic_input"}}
    elif tool == "press_key":
        press_key(require_non_empty_string(operation.get("key"), "key"))
        action = {"path": "synthetic", "actionName": "pressKey", "fallbackReason": None, "verification": {"state": "unverified", "reason": "synthetic_input"}}
    elif tool == "hotkey":
        hotkey(require_non_empty_string(operation.get("key"), "key"))
        action = {"path": "synthetic", "actionName": "hotkey", "fallbackReason": None, "verification": {"state": "unverified", "reason": "synthetic_input"}}
    elif tool == "paste_text":
        paste_text(require_non_empty_string(operation.get("text"), "text"))
        action = {"path": "clipboard", "actionName": "paste", "fallbackReason": None, "verification": {"state": "unverified", "reason": "clipboard_paste"}}
    elif tool == "set_value":
        if not set_value(node, operation.get("value", "")):
            raise RuntimeError("element value is not settable")
        action = {"path": "accessibility", "actionName": "setValue", "fallbackReason": None}
    else:
        raise RuntimeError("unknown tool: " + str(tool))

    try:
        snapshot = make_snapshot(
            operation.get("app", ""),
            include_screenshot,
            operation.get("windowId"),
            operation.get("windowIndex"),
        )
    except Exception:
        if operation.get("windowId") is None and operation.get("windowIndex") is None:
            raise
        action.setdefault("verification", {"state": "unverified", "reason": "window_changed"})
        snapshot = make_snapshot(operation.get("app", ""), include_screenshot, None, None)

    return {"ok": True, "action": action, "snapshot": snapshot}


def main():

View on GitHub (pinned to 1136503c6a)

Solutions

1. Use one of the documented tool names exactly; consult handshake_response capabilities for the supported set.
2. Upgrade/downgrade the client and runtime to matching versions so the tool vocabulary aligns.
3. Check the operation dict construction for typos or a missing 'tool' key.

Example fix

// before
{"tool":"clic","element":3}
// after
{"tool":"click","element":3}

KNOWN_TOOLS = {"handshake","list_apps","list_windows","get_app_state","click","perform_secondary_action","scroll","drag","type_text","press_key","hotkey","paste_text","set_value"}
if op.get("tool") not in KNOWN_TOOLS:
    raise ValueError(f"unknown tool: {op.get('tool')!r}")

KNOWN_TOOLS = {"handshake","list_apps","list_windows","get_app_state","click","perform_secondary_action","scroll","drag","type_text","press_key","hotkey","paste_text","set_value"}

def is_known_tool(op) -> bool:
    return op.get("tool") in KNOWN_TOOLS

try:
    run_operation(op)
except RuntimeError as e:
    if "unknown tool" in str(e):
        raise ValueError(f"unsupported tool {op.get('tool')!r}; check runtime version") from e
    raise

When it happens

Trigger: Sending an operation whose 'tool' field is a typo ('clic'), a renamed tool from a different version, an unsupported verb ('hover' — not implemented), or missing/None. None is stringified to 'None'.

Common situations: Version skew between the client/agent and the runtime (a tool was added/renamed in a newer version); a typo in a hand-built operation; an agent hallucinates a verb not in the protocol.

Related errors

• {name} must be a positive number
• {name} is required
• unsupported mouse button: {button}
• click modifiers require modifier keys only
• direction is required

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/e9bbf141dc76253d. Report an issue: GitHub.