What causes "Usage: ghidra trace put-threads" in NationalSecurityAgency/ghidra?

Invoke bare: `ghidra trace put-threads`.

NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace put-threads

Error message

Usage: ghidra trace put-threads

What it means

Raised by ghidra_trace_put_threads when any argument is given. put_threads publishes the current process's threads into the trace; the command is parameterless (commands.py:1890).

Source

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

            procnum=proc.GetProcessID(), tnum=t.GetThreadID())
        tobj = trace.proxy_object_path(tpath)
    else:
        tobj = None
    trace.proxy_object_path('').set_value('_event_thread', tobj)


@convert_errors
def ghidra_trace_put_threads(debugger: lldb.SBDebugger, command: str,
                             result: lldb.SBCommandReturnObject,
                             internal_dict: Dict[str, Any]) -> None:
    """Put the current process's threads into the Ghidra trace.

    Usage: ghidra trace put-threads
    """

    args = shlex.split(command)
    if len(args) != 0:
        raise RuntimeError("Usage: ghidra trace put-threads")

    trace, tx = STATE.require_tx()
    with trace.client.batch() as b:
        put_threads()


def put_frames() -> None:
    proc = util.get_process()
    trace = STATE.require_trace()
    mapper = trace.extra.require_mm()
    t = util.selected_thread()
    if t is None:
        return
    keys = []
    for i in range(0, t.GetNumFrames()):
        f = t.GetFrameAtIndex(i)
        fpath = FRAME_PATTERN.format(
            procnum=proc.GetProcessID(), tnum=t.GetThreadID(), level=f.GetFrameID())

View on GitHub (pinned to d5f144c24d)

Solutions

Invoke bare: `ghidra trace put-threads`.
To focus a thread, select it in LLDB (thread select) then use put-frames; put-threads itself takes no selector.

Example fix

// before
ghidra trace put-threads 2
// after
ghidra trace put-threads

Defensive patterns

Strategy: validation

Validate before calling

assert len(command.split()) == 0, "put-threads takes no arguments"

Prevention

put-threads publishes all threads of the current process.
Use 'thread select' in LLDB to change selection, not an arg here.

When it happens

Trigger: Passing a thread id or index, e.g. `ghidra trace put-threads 2`, or trailing text after the command.

Common situations: Users assume a thread selector like LLDB's `thread list`; the agent publishes all threads for the current process.

Related errors

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