stablyai/orca · warning · RuntimeError

{name} must be a positive integer

Error message

{name} must be a positive integer

What it means

Raised by require_positive_integer (runtime.py:802-809) when a value cannot be parsed as a strictly-positive integer: int(value) raises (TypeError for None/non-numeric objects, ValueError for non-numeric strings) OR parsed ≤ 0. The {name} placeholder identifies which parameter failed — at call sites, 'click_count' (line 1067/833) is the primary caller. Note that 0 and negative integers fail even though they parse, and floats like '1.5' fail (int('1.5') raises ValueError).

Source

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

    return bool(index is not None and attempt(lambda: node.do_action(int(index)), False))


def screen_point(window_rect, saved_element=None, x=None, y=None, node=None):
    rect = screen_rect(node) if node is not None else None
    if rect is not None:
        return rect.x + rect.width / 2, rect.y + rect.height / 2
    if saved_element is not None:
        raise RuntimeError("stale element frame; run get-app-state again and use a fresh element index")
    if window_rect is None or x is None or y is None:
        raise RuntimeError("coordinate action requires a visible window and coordinates")
    return window_rect.x + float(x), window_rect.y + float(y)


def require_positive_integer(value, name):
    try:
        parsed = int(value)
    except (TypeError, ValueError):
        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")

View on GitHub (pinned to 1136503c6a)

Solutions

  1. Omit click_count entirely to accept the default of 1, OR pass a positive integer ≥ 1.
  2. If the intent was a single click, pass click_count:1 explicitly rather than relying on edge values.
  3. Validate click_count is a positive integer on the caller side before dispatching the operation JSON.
  4. For drag/scroll helpers, ensure 'pages' (validated via require_positive_number, which allows floats) is distinguished from click_count (integers only).

Example fix

// before — invalid click counts
{ "tool": "click", "click_count": 0 }   // <= 0
{ "tool": "click", "click_count": "2" } // string ok if numeric, but '1.5' fails
{ "tool": "click", "click_count": -1 } // negative

// after — positive integer or omitted
{ "tool": "click", "click_count": 2 }
{ "tool": "click" } // defaults to 1
Defensive patterns

Strategy: validation

Validate before calling

# Validate click_count before dispatch
import numbers
def is_positive_int(value) -> bool:
    return isinstance(value, int) and not isinstance(value, bool) and value > 0
# usage:
if 'click_count' in operation and operation['click_count'] is not None:
    if not is_positive_int(operation['click_count']):
        raise SystemExit(f'click_count must be a positive integer, got {operation["click_count"]!r}')

Type guard

def is_valid_positive_integer(value, name: str) -> bool:
    try:
        parsed = int(value)
    except (TypeError, ValueError):
        return False
    return parsed > 0

Try / catch

try:
    run_operation(operation)
except RuntimeError as exc:
    if 'must be a positive integer' in str(exc):
        # coerce or default: drop click_count to accept default of 1
        operation = {k: v for k, v in operation.items() if k != 'click_count'}
        operation.setdefault('click_count', 1)
        run_operation(operation)
    else:
        raise

Prevention

When it happens

Trigger: operation.get('click_count') is non-null and either non-numeric (string 'abc', null-cast, object), a float string ('1.5'), or ≤ 0 (0, -1, '0'). Also any future caller of require_positive_integer passing a defaulted/missing field that resolves to None or 0. The check at line 1067-1069 only runs require_positive_integer when click_count is not None, so omitting it entirely is safe (defaults to 1).

Common situations: Agent passed click_count:0 (perhaps meaning 'no click, just hover' — unsupported) or a fractional/negative value; a templated caller defaulted click_count to 0 or a string; JSON deserialization produced a float where an int was expected.

Related errors

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