NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace insert-obj PATH

Error message

Usage: ghidra trace insert-obj PATH

What it means

Usage error raised by ghidra_trace_insert_obj when the token count is not exactly 1. insert_obj finishes a detached object by creating its ancestry across the object's lifespan; it requires the single PATH previously passed to create-obj.

Source

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

    result.PutCString(f"Created object: id={obj.id}, path='{obj.path}'")


@convert_errors
def ghidra_trace_insert_obj(debugger: lldb.SBDebugger, command: str,
                            result: lldb.SBCommandReturnObject,
                            internal_dict: Dict[str, Any]) -> None:
    """Insert an object into the Ghidra trace.

    Usage: ghidra trace insert-obj PATH

    See 'ghidra trace create-obj'. An object in a detached state is missing
    some or all of its ancestry for its lifespan. Inserting the object creates
    its ancestry for its whole lifespan.
    """

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

    # NOTE: id parameter is probably not necessary, since this command is for
    # humans.
    trace, tx = STATE.require_tx()
    span = trace.proxy_object_path(path).insert()
    result.PutCString(f"Inserted object: lifespan={span}")


@convert_errors
def ghidra_trace_remove_obj(debugger: lldb.SBDebugger, command: str,
                            result: lldb.SBCommandReturnObject,
                            internal_dict: Dict[str, Any]) -> None:
    """Remove an object from the Ghidra trace.

    Usage: ghidra trace remove-obj PATH

    This does not delete the object. It just removes it from the tree for the

View on GitHub (pinned to d5f144c24d)

Solutions

1. Pass exactly one PATH token matching the one used in create-obj.
2. Quote the command so the bracketed PATH is a single token.
3. Ensure create-obj was called for that PATH first.

Example fix

// before
ghidra trace insert-obj Processes[0] Threads[1]
// after
ghidra trace insert-obj Processes[0].Threads[1]

import shlex

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

def is_single_path_token(command: str) -> bool:
    return len(shlex.split(command)) == 1

try:
    ghidra_trace_insert_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 path; trailing flags; mismatched PATH between create and insert.

Common situations: User forgets to quote a bracketed path; user runs insert-obj before create-obj; user passes extra arguments.

Related errors

• Usage: ghidra trace create-obj PATH
• Usage: ghidra trace remove-obj PATH
• Usage: ghidra trace get-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/cb38bd2a5c446c48. Report an issue: GitHub.