What causes "Usage: ghidra trace get-values PATTERN" in NationalSecurityAgency/ghidra?

Pass exactly one PATTERN token, using [] or trailing period for wildcards.

NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace get-values PATTERN

Error message

Usage: ghidra trace get-values PATTERN

What it means

Usage error raised by ghidra_trace_get_values when the token count is not exactly 1. get_values takes a single PATTERN where blanks act as wildcards (e.g. Processes[].Threads[]) and prints matching values tabularly.

Source

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

                            result: lldb.SBCommandReturnObject,
                            internal_dict: Dict[str, Any]) -> None:
    """List all values matching a given path pattern.

    Usage: ghidra trace get-values PATTERN

    PATTERN is a path where blanks indicate wild cards. Beware, this may seem a
    little odd, esp., when the final key is a wild card. Here are some examples:

       Processes[]             To get all processes
       Processes[0].Threads[]  To get all threads in the first process
       Processes[].Threads[]   To get all threads from all processes
       Processes[0].           (Note the trailing period) to get all attributes
                               of the first process
    """

    args = shlex.split(command)
    if len(args) != 1:
        raise RuntimeError("Usage: ghidra trace get-values PATTERN")
    pattern = args[0]

    trace = STATE.require_trace()
    values = wait(trace.get_values(pattern))
    print_tabular_values(values, result.PutCString)


@convert_errors
def ghidra_trace_get_values_rng(debugger: lldb.SBDebugger, command: str,
                                result: lldb.SBCommandReturnObject,
                                internal_dict: Dict[str, Any]) -> None:
    """List all values intersecting a given address range.

    Usage: ghidra trace get-values-rng ADDRESS LENGTH

    This can only retrieve values of type ADDRESS or RANGE.
    NOTE: Even in batch mode, this request will block for the result.
    """

View on GitHub (pinned to d5f144c24d)

Solutions

Pass exactly one PATTERN token, using [] or trailing period for wildcards.
Quote the command so the pattern is a single token.
For a single known object, use get-obj; for a range query use get-values-rng.

Example fix

// before
ghidra trace get-values Processes[0].Threads[1] Registers
// after
ghidra trace get-values Processes[0].Threads[].Registers[]

Defensive patterns

Strategy: validation

Validate before calling

import shlex

def validate_get_values(command: str) -> None:
    if len(shlex.split(command)) != 1:
        raise ValueError('get-values needs exactly one PATTERN token')

Type guard

def is_pattern(tok: str) -> bool:
    # patterns use [] wildcards or a trailing period
    return '[]' in tok or tok.endswith('.')

Try / catch

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

Prevention

Pass one PATTERN token using [] or trailing period for wildcards.
Use get-obj for a single object, get-values-rng for a memory range.
Quote patterns to keep them as one token.

When it happens

Trigger: Zero tokens; passing multiple patterns; quoting that splits the pattern; passing flags the command does not accept.

Common situations: User passes a plain PATH instead of a pattern with wildcards; user adds trailing arguments; user forgets the pattern entirely.

Related errors

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