NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace get-obj PATH

Error message

Usage: ghidra trace get-obj PATH

What it means

Usage error raised by ghidra_trace_get_obj when the token count is not exactly 1. get_obj looks up a single object descriptor by canonical PATH and prints its id and path; it confirms existence of one object.

Source

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

    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.
    """

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

    trace = STATE.require_trace()
    object = trace.get_object(path)
    result.PutCString(f"{object.id}\t{object.path}")


@convert_errors
def ghidra_trace_get_values(debugger: lldb.SBDebugger, command: str,
                            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:

View on GitHub (pinned to d5f144c24d)

Solutions

1. Pass exactly one canonical PATH token (no wildcards).
2. Quote the command so PATH stays one token.
3. For wildcard/pattern queries, use 'ghidra trace get-values PATTERN' instead.

Example fix

// before
ghidra trace get-obj Processes[]
// after
ghidra trace get-obj Processes[0]

import shlex

def validate_get_obj(command: str) -> None:
    if len(shlex.split(command)) != 1:
        raise ValueError('get-obj needs exactly one PATH token (no wildcards)')

def is_canonical_path(tok: str) -> bool:
    # canonical paths use explicit indices, not blanks/wildcards
    return '[' in tok and '[]' not in tok

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

When it happens

Trigger: Zero tokens; multi-token unquoted path; passing a wildcard pattern (use get-values for patterns); passing flags.

Common situations: User passes a pattern like Processes[] expecting wildcard matching (get_obj does not pattern-match); user forgets to quote a bracketed path.

Related errors

• Usage: ghidra trace create-obj PATH
• Usage: ghidra trace insert-obj PATH
• Usage: ghidra trace remove-obj PATH
• Usage: ghidra trace get-values PATTERN
• Usage: ghidra trace putmem ADDRESS LENGTH [PAGES]

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