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.

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 create-obj PATH
• Usage: ghidra trace delmem ADDRESS LENGTH
• Usage: ghidra trace delreg [GROUP]
• Usage: ghidra trace get-obj PATH
• Usage: ghidra trace get-values PATTERN

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

Appendix: 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)