stablyai/orca · error · RuntimeError

{name} is required

Error message

{name} is required

What it means

Raised by require_non_empty_string (runtime.py:824) when value is None or str(value) == ''. It is the presence guard for required textual fields. Call sites pass name='key' for press_key and hotkey (runtime.py:1111, 1114) and name='text' for type_text and paste_text (runtime.py:1108, 1117).

Source

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

        raise RuntimeError(f"{name} must be a positive integer")
    if parsed <= 0:
        raise RuntimeError(f"{name} must be a positive integer")
    return parsed


def require_positive_number(value, name):
    try:
        parsed = float(value)
    except (TypeError, ValueError):
        raise RuntimeError(f"{name} must be a positive number")
    if not math.isfinite(parsed) or parsed <= 0:
        raise RuntimeError(f"{name} must be a positive number")
    return parsed


def require_non_empty_string(value, name):
    if value is None or str(value) == "":
        raise RuntimeError(f"{name} is required")
    return str(value)


def click_at(x, y, button, count, modifiers=None):
    button = (button or "left").lower()
    buttons = {"left": ("b1p", "b1r"), "right": ("b3p", "b3r"), "middle": ("b2p", "b2r")}
    if button not in buttons:
        raise RuntimeError(f"unsupported mouse button: {button}")
    parsed_count = require_positive_integer(1 if count is None else count, "click_count")
    modifier_keys = click_modifier_keys(modifiers)
    if modifier_keys:
        modified_click_at(x, y, button, parsed_count, modifier_keys)
        return
    down, up = buttons[button]
    for _ in range(parsed_count):
        Atspi.generate_mouse_event(round(x), round(y), "abs")
        Atspi.generate_mouse_event(round(x), round(y), down)
        time.sleep(0.03)

View on GitHub (pinned to 1136503c6a)

Solutions

1. Always include a non-empty 'key' for press_key/hotkey or 'text' for type_text/paste_text.
2. Skip dispatching the operation entirely when the relevant field is empty rather than sending it to fail.
3. If the field is user input, validate non-emptiness in your UI/controller before calling run_operation.

Example fix

// before
{"tool":"type_text","text":""}
// after
{"tool":"type_text","text":"hello"}

def require_text(value, field):
    if value is None or str(value).strip() == "":
        raise ValueError(f"{field} is required")
    return str(value)

op = {"tool": "type_text", "text": require_text(raw_text, "text")}

def is_non_empty(value) -> bool:
    return value is not None and str(value) != ""

try:
    run_operation(op)
except RuntimeError as e:
    if "is required" in str(e):
        # skip the action; nothing to type
        pass
    else:
        raise

When it happens

Trigger: Invoking press_key/hotkey with operation['key'] missing, null, or empty; invoking type_text/paste_text with operation['text'] missing, null, or empty string. Only a literally empty string trips this — whitespace-only strings like ' ' pass through.

Common situations: An agent template forgets to populate the key/text field; a caller sends {'tool':'press_key'} with no 'key'; a paste_text operation is dispatched with an empty clipboard payload.

Related errors

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

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