NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace restart [NAME]

Error message

Usage: ghidra trace restart [NAME]

What it means

`ghidra trace restart` accepts 0 or 1 arguments: it closes any existing trace, resets it, then starts a new one with the given or auto-derived name. Two or more tokens abort.

Source

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

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

    Usage: ghidra trace restart [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 restart [NAME]")

    STATE.require_client()
    if STATE.trace is not None:
        STATE.trace.close()
        STATE.reset_trace()
    start_trace(name)


@convert_errors
def ghidra_trace_info(debugger: lldb.SBDebugger, command: str,
                      result: lldb.SBCommandReturnObject,
                      internal_dict: Dict[str, Any]) -> None:
    """Get info about the Ghidra connection.

    Usage: ghidra trace info
    """

    args = shlex.split(command)

View on GitHub (pinned to d5f144c24d)

Solutions

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

Example fix

// before
ghidra trace restart my trace
// after
ghidra trace restart "my trace"
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: `ghidra trace restart my trace` (unquoted multi-word name); `ghidra trace restart a b`.

Common situations: A multi-word trace name not quoted, splitting into too many tokens.

Related errors

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