NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace start [NAME]

Error message

Usage: ghidra trace start [NAME]

What it means

`ghidra trace start` accepts 0 arguments (the name is auto-derived from the target image via `compute_name`) or 1 argument (an explicit name). Two or more tokens abort before `require_client`/`require_no_trace` run.

Source

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

@convert_errors
def ghidra_trace_start(debugger: lldb.SBDebugger, command: str,
                       result: lldb.SBCommandReturnObject,
                       internal_dict: Dict[str, Any]) -> None:
    """Start a Trace in Ghidra.

    Usage: ghidra trace start [NAME]

    Takes an optional name for the trace. If omitted, it tries to derive the
    name from the target image.
    """

    args = shlex.split(command)
    if len(args) == 0:
        name = compute_name()
    elif len(args) == 1:
        name = args[0]
    else:
        raise RuntimeError("Usage: ghidra trace start [NAME]")

    STATE.require_client()
    STATE.require_no_trace()
    start_trace(name)


@convert_errors
def ghidra_trace_stop(debugger: lldb.SBDebugger, command: str,
                      result: lldb.SBCommandReturnObject,
                      internal_dict: Dict[str, Any]) -> None:
    """Stop the Trace in Ghidra.

    Usage: ghidra trace stop
    """

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

View on GitHub (pinned to d5f144c24d)

Solutions

1. Quote a multi-word name: `ghidra trace start "my trace"`
2. Or omit the name to auto-derive it from the target image: `ghidra trace start`

Example fix

// before
ghidra trace start my trace
// after
ghidra trace start "my trace"

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

try:
    ghidra_trace_start(debugger, command, result, internal_dict)
except RuntimeError as e:
    if str(e).startswith('Usage: ghidra trace start'):
        # quote a multi-word name or drop extra tokens and retry
        ...
    raise

When it happens

Trigger: `ghidra trace start my trace` (an unquoted name with a space becomes two tokens); `ghidra trace start a b`.

Common situations: A trace name containing spaces passed without quotes, so shlex splits it into multiple tokens.

Related errors

• Usage: ghidra trace stop
• Usage: ghidra trace restart [NAME]
• Usage: ghidra trace save
• Usage: ghidra trace new-snap [SNAP] DESCRIPTION
• Usage: ghidra trace connect ADDRESS

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