NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace new-snap [SNAP] DESCRIPTION

Error message

Usage: ghidra trace new-snap [SNAP] DESCRIPTION

What it means

`ghidra trace new-snap` creates a snapshot and requires a DESCRIPTION; an optional leading SNAP schedule may precede it (only when exactly two args are given, `Schedule(int(args[0]))`). Zero args (no description) or three or more raise this. Note a lone number is treated as the DESCRIPTION, not as the SNAP.

Source

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

def ghidra_trace_new_snap(debugger: lldb.SBDebugger, command: str,
                          result: lldb.SBCommandReturnObject,
                          internal_dict: Dict[str, Any]) -> None:
    """Create a new snapshot.

    Usage: ghidra trace new-snap [SNAP] DESCRIPTION

    Subsequent modifications to machine state will affect the new snapshot.
    """

    args = shlex.split(command)
    if len(args) == 1:
        time = None
        description = args[0]
    elif len(args) == 2:
        time = Schedule(int(args[0]))
        description = args[1]
    else:
        raise RuntimeError("Usage: ghidra trace new-snap [SNAP] DESCRIPTION")
    STATE.require_trace().snapshot(description, time=time)


def quantize_pages(start: int, end: int) -> Tuple[int, int]:
    return (start // PAGE_SIZE * PAGE_SIZE, (end+PAGE_SIZE-1) // PAGE_SIZE*PAGE_SIZE)


def check_count(actual: int, requested: int):
    if actual != requested: 
        print(f"Incomplete read: {actual} bytes")
    

def put_bytes(start: int, end: int, result: lldb.SBCommandReturnObject,
              pages: bool) -> None:
    trace = STATE.require_trace()
    if pages:
        start, end = quantize_pages(start, end)
    proc = util.get_process()

View on GitHub (pinned to d5f144c24d)

Solutions

  1. Provide a description, optionally preceded by a SNAP: `ghidra trace new-snap "after breakpoint"` or `ghidra trace new-snap 5 "after breakpoint"`
  2. Quote multi-word descriptions so the total token count is 1 or 2

Example fix

// before
ghidra trace new-snap after breakpoint
// after
ghidra trace new-snap "after breakpoint"
Defensive patterns

Strategy: validation

Validate before calling

import shlex
def one_or_two_args(command: str) -> bool:
    return len(shlex.split(command)) in (1, 2)

Try / catch

try:
    ghidra_trace_new_snap(debugger, command, result, internal_dict)
except RuntimeError as e:
    if str(e).startswith('Usage: ghidra trace new-snap'):
        # quote the description (and optional leading SNAP) and retry
        ...
    raise

Prevention

When it happens

Trigger: `ghidra trace new-snap` (no description); `ghidra trace new-snap a b c`; `ghidra trace new-snap 5 stopped at main` (the unquoted description makes three tokens).

Common situations: Forgetting the description; a multi-word description not quoted; expecting SNAP and DESCRIPTION to both be independently optional.

Related errors

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