{"record":{"id":"e9bbf141dc76253d","repo":"stablyai/orca","slug":"unknown-tool-tool","errorCode":null,"errorMessage":"unknown tool: {tool}","messagePattern":"unknown tool: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"native/computer-use-linux/runtime.py","lineNumber":1124,"sourceCode":"        action = {\"path\": \"synthetic\", \"actionName\": \"drag\", \"fallbackReason\": None}\n    elif tool == \"type_text\":\n        type_text(require_non_empty_string(operation.get(\"text\"), \"text\"))\n        action = {\"path\": \"synthetic\", \"actionName\": \"typeText\", \"fallbackReason\": None, \"verification\": {\"state\": \"unverified\", \"reason\": \"synthetic_input\"}}\n    elif tool == \"press_key\":\n        press_key(require_non_empty_string(operation.get(\"key\"), \"key\"))\n        action = {\"path\": \"synthetic\", \"actionName\": \"pressKey\", \"fallbackReason\": None, \"verification\": {\"state\": \"unverified\", \"reason\": \"synthetic_input\"}}\n    elif tool == \"hotkey\":\n        hotkey(require_non_empty_string(operation.get(\"key\"), \"key\"))\n        action = {\"path\": \"synthetic\", \"actionName\": \"hotkey\", \"fallbackReason\": None, \"verification\": {\"state\": \"unverified\", \"reason\": \"synthetic_input\"}}\n    elif tool == \"paste_text\":\n        paste_text(require_non_empty_string(operation.get(\"text\"), \"text\"))\n        action = {\"path\": \"clipboard\", \"actionName\": \"paste\", \"fallbackReason\": None, \"verification\": {\"state\": \"unverified\", \"reason\": \"clipboard_paste\"}}\n    elif tool == \"set_value\":\n        if not set_value(node, operation.get(\"value\", \"\")):\n            raise RuntimeError(\"element value is not settable\")\n        action = {\"path\": \"accessibility\", \"actionName\": \"setValue\", \"fallbackReason\": None}\n    else:\n        raise RuntimeError(\"unknown tool: \" + str(tool))\n\n    try:\n        snapshot = make_snapshot(\n            operation.get(\"app\", \"\"),\n            include_screenshot,\n            operation.get(\"windowId\"),\n            operation.get(\"windowIndex\"),\n        )\n    except Exception:\n        if operation.get(\"windowId\") is None and operation.get(\"windowIndex\") is None:\n            raise\n        action.setdefault(\"verification\", {\"state\": \"unverified\", \"reason\": \"window_changed\"})\n        snapshot = make_snapshot(operation.get(\"app\", \"\"), include_screenshot, None, None)\n\n    return {\"ok\": True, \"action\": action, \"snapshot\": snapshot}\n\n\ndef main():","sourceCodeStart":1106,"sourceCodeEnd":1142,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/native/computer-use-linux/runtime.py#L1106-L1142","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Use one of the documented tool names exactly; consult handshake_response capabilities for the supported set.","Upgrade/downgrade the client and runtime to matching versions so the tool vocabulary aligns.","Check the operation dict construction for typos or a missing 'tool' key."],"exampleFix":"// before\n{\"tool\":\"clic\",\"element\":3}\n// after\n{\"tool\":\"click\",\"element\":3}","handlingStrategy":"type-guard","validationCode":"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\"}\nif op.get(\"tool\") not in KNOWN_TOOLS:\n    raise ValueError(f\"unknown tool: {op.get('tool')!r}\")","typeGuard":"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\"}\n\ndef is_known_tool(op) -> bool:\n    return op.get(\"tool\") in KNOWN_TOOLS","tryCatchPattern":"try:\n    run_operation(op)\nexcept RuntimeError as e:\n    if \"unknown tool\" in str(e):\n        raise ValueError(f\"unsupported tool {op.get('tool')!r}; check runtime version\") from e\n    raise","preventionTips":["Keep client and runtime versions aligned so the tool vocabulary matches.","Validate the 'tool' field against the handshake capabilities before dispatch.","Build operations from typed constants rather than ad-hoc strings."],"tags":["computer-use","input-validation","protocol","python"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}