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.

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 get-obj PATH
• Usage: ghidra trace get-values PATTERN
• Usage: ghidra trace remove-obj PATH
• Usage: ghidra trace delmem ADDRESS LENGTH

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

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