NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace create-obj PATH

Error message

Usage: ghidra trace create-obj PATH

What it means

Usage error raised by ghidra_trace_create_obj when the token count is not exactly 1. create_obj needs a single fully-qualified object PATH (e.g. Processes[0].Threads[1]); the new object is created in a detached state and later inserted with insert-obj.

Source

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

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

    Usage: ghidra trace create-obj PATH

    PATH gives the objects fully-qualified name, e.g., Processes[0].Threads[1],
    which often denotes the second thread of the first target process.

    The new object is in a detached state, so it may not be immediately
    recognized by the Debugger GUI. Use 'ghidra trace insert-obj' to finish the
    object, after all its required attributes are set.
    """

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

    trace, tx = STATE.require_tx()
    obj = trace.create_object(path)
    obj.insert()
    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

View on GitHub (pinned to d5f144c24d)

Solutions

1. Pass exactly one PATH token.
2. If the path contains characters shlex would split on, wrap the entire command so PATH stays one token.
3. Use canonical indexed path syntax like Processes[0].Memory[].

Example fix

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

import shlex

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

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

try:
    ghidra_trace_create_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: Passing zero paths or a multi-token path that was not quoted; passing additional flags; whitespace inside an unquoted path.

Common situations: User forgets to quote a path containing brackets/spaces; user tries to create several objects at once; user passes options.

Related errors

• Usage: ghidra trace insert-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/d06fbb51dc2fbf15. Report an issue: GitHub.