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

Run the command bare: `ghidra trace put-processes`.

NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace put-processes

Error message

Usage: ghidra trace put-processes

What it means

Raised by ghidra_trace_put_processes when any argument is supplied. put-processes takes no parameters: it enumerates the live target's processes and writes them into the trace's Processes list. The len(args)!=0 guard at commands.py:1487 rejects all tokens.

Source

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

        with trace.open_tx('State'):
            procobj = trace.create_object(ipath)
            state = "STOPPED" if event_process.is_stopped else "RUNNING"
            procobj.set_value('State', state)
            procobj.insert()


@convert_errors
def ghidra_trace_put_processes(debugger: lldb.SBDebugger, command: str,
                               result: lldb.SBCommandReturnObject,
                               internal_dict: Dict[str, Any]) -> None:
    """Put the list of processes into the trace's Processes list.

    Usage: ghidra trace put-processes
    """

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

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


def put_available() -> None:
    trace = STATE.require_trace()
    availables = util.AVAILABLE_INFO_READER.get_availables()
    keys = []
    for proc in availables:
        ppath = AVAILABLE_PATTERN.format(pid=proc.pid)
        procobj = trace.create_object(ppath)
        keys.append(AVAILABLE_KEY_PATTERN.format(pid=proc.pid))
        procobj.set_value('PID', proc.pid)
        if isinstance(proc, util.Available):
        	procobj.set_value('Name', proc.name)
        	procobj.set_value('_display', f'{proc.pid} {proc.command}')

View on GitHub (pinned to d5f144c24d)

Solutions

Run the command bare: `ghidra trace put-processes`.
If you meant a specific process, select it in LLDB (process select / target) then run put-processes, or use put-all.
Sanitize wrapper scripts so no extra tokens are appended.

Example fix

// before
ghidra trace put-processes 1234
// after
ghidra trace put-processes

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

All put-* zero-arg commands reflect current LLDB selection — never pass a selector.
Select the process in LLDB first when you need a specific one.
Strip template placeholders from scripted commands.

When it happens

Trigger: Typing `ghidra trace put-processes all`, appending a process id thinking it filters (`put-processes 1234`), or stray trailing text/quotes after the command name.

Common situations: Users coming from gdb/other agents expect a selector argument; or a script concatenates a variable that is empty in some runs and non-empty in others, adding an unwanted token.

Related errors

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