NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace set-value PATH KEY VALUE [SCHEMA]

Error message

Usage: ghidra trace set-value PATH KEY VALUE [SCHEMA]

What it means

Usage error raised by ghidra_trace_set_value when the token count is not 3 or 4. The command requires PATH, KEY, VALUE, and optionally an explicit SCHEMA; the SCHEMA is parsed via sch.Schema(args[3]) and must be a valid schema name.

Source

Thrown at Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py:1235

    # humans.
    # TODO: path and key are two separate parameters.... This is mostly to
    # spare me from porting path parsing to Python, but it may also be useful
    # if we ever allow ids here, since the id would be for the object, not the
    # complete value path.

    args = shlex.split(command)
    if len(args) == 3:
        path = args[0]
        key = args[1]
        value = args[2]
        schema = None
    elif len(args) == 4:
        path = args[0]
        key = args[1]
        value = args[2]
        schema = sch.Schema(args[3])
    else:
        raise RuntimeError(
            "Usage: ghidra trace set-value PATH KEY VALUE [SCHEMA]")

    trace, tx = STATE.require_tx()
    if schema == sch.OBJECT:
        val: Union[bool, int, float, bytes, Tuple[str, Address], List[bool],
                   List[int], str, TraceObject, Address,
                   None] = trace.proxy_object_path(value)
    else:
        val, schema = eval_value(value, schema)
        if schema == sch.ADDRESS and isinstance(val, tuple):
            base, addr = val
            val = addr
            if base != addr.space:
                trace.create_overlay_space(base, addr.space)
    trace.proxy_object_path(path).set_value(key, val, schema)


retain_values_parser = optparse.OptionParser(prog='ghidra trace retain-values',

View on GitHub (pinned to d5f144c24d)

Solutions

1. Pass exactly 3 tokens (PATH KEY VALUE) or 4 (PATH KEY VALUE SCHEMA).
2. Use a KEY of the form [INDEX] to denote an element, or a plain name for an attribute.
3. If supplying SCHEMA, confirm it is one of sch.Schema's valid names (e.g. BOOL, LONG, ADDRESS, STRING).

Example fix

// before
ghidra trace set-value Processes[0].Threads[1] pc
// after
ghidra trace set-value Processes[0].Threads[1] pc $pc ADDRESS

import shlex
from ghidralldb import schema as sch

def validate_set_value(command: str) -> None:
    toks = shlex.split(command)
    if len(toks) not in (3, 4):
        raise ValueError('set-value needs PATH KEY VALUE [SCHEMA]')
    if len(toks) == 4:
        sch.Schema(toks[3])  # raises early on invalid schema name

def key_is_element(key: str) -> bool:
    return key.startswith('[') and key.endswith(']')

try:
    ghidra_trace_set_value(debugger, command, result, internal_dict)
except (RuntimeError, ValueError) as e:
    result.SetError(str(e))

When it happens

Trigger: Wrong token count; passing an invalid schema name (which throws inside sch.Schema before reaching this message); quoting issues that split PATH/KEY.

Common situations: User omits KEY or VALUE; user passes a flag; user supplies a SCHEMA string that is not a recognized schema enum.

Related errors

• Usage: ghidra trace putmem ADDRESS LENGTH [PAGES]
• Usage: ghidra trace putval EXPRESSION [PAGES]
• Usage: ghidra trace putmem ADDRESS LENGTH STATE [PAGES]
• Usage: ghidra trace delmem ADDRESS LENGTH
• Usage: ghidra trace putreg [GROUP]

AI-assisted analysis of NationalSecurityAgency/ghidra@d5f144c24d (2026-08-14). Data as JSON: /api/errors/207e8011d27849a8. Report an issue: GitHub.