NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace retain-values [OPTIONS] PATH [KEYS...]

Error message

Usage: ghidra trace retain-values [OPTIONS] PATH [KEYS...]

What it means

Usage error raised by ghidra_trace_retain_values when, after retain_values_parser.parse_args, fewer than one positional argument remains. retain_values keeps the named KEYS on the object at PATH and nulls the rest; PATH is mandatory, KEYS may be empty.

Source

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

                               result: lldb.SBCommandReturnObject,
                               internal_dict: Dict[str, Any]) -> None:
    """Retain only those keys listed, setting all others to null.

    Usage: ghidra trace retain-values [OPTIONS] PATH [KEYS...]

    OPTIONS may be one of:

        --elements To set all other elements to null (default)
        --attributes To set all other attributes to null
        --both To set all other values (elements and attributes) to null

    KEYS is a space-separated list of keys to keep. This list may be empty, in
    which case, all keys of the specified kind are removed.
    """

    options, args = retain_values_parser.parse_args(shlex.split(command))
    if len(args) < 1:
        raise RuntimeError(
            "Usage: ghidra trace retain-values [OPTIONS] PATH [KEYS...]")
    path = args[0]
    keys = args[1:]

    trace, tx = STATE.require_tx()
    trace.proxy_object_path(path).retain_values(keys, kinds=options.kinds)


@convert_errors
def ghidra_trace_get_obj(debugger: lldb.SBDebugger, command: str,
                         result: lldb.SBCommandReturnObject,
                         internal_dict: Dict[str, Any]) -> None:
    """Get an object descriptor by its canonical path.

    Usage: ghidra trace get-obj PATH

    This isn't the most informative, but it will at least confirm whether an
    object exists and provide its id.

View on GitHub (pinned to d5f144c24d)

Solutions

1. Always supply a PATH token, even if KEYS is empty.
2. Use only supported options: --elements, --attributes, --both.
3. Place options before PATH to avoid the parser consuming PATH as an option value.

Example fix

// before
ghidra trace retain-values --attributes
// after
ghidra trace retain-values --attributes Processes[0].Threads[1]

from ghidralldb.commands import retain_values_parser
import shlex

def validate_retain_values(command: str) -> None:
    opts, args = retain_values_parser.parse_args(shlex.split(command))
    if len(args) < 1:
        raise ValueError('retain-values needs a PATH (KEYS optional)')

try:
    ghidra_trace_retain_values(debugger, command, result, internal_dict)
except RuntimeError as e:
    if str(e).startswith('Usage:'):
        result.SetError(str(e))
    else:
        raise

When it happens

Trigger: Passing only options (--elements/--attributes/--both) with no PATH; passing an option the parser does not recognize so PATH is consumed as an option; empty command string.

Common situations: User forgets PATH and supplies only flags; user misspells an option so the parser treats PATH as an unknown option argument.

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/63b669fdeffe9312. Report an issue: GitHub.