NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace tx-start DESCRIPTION

Error message

Usage: ghidra trace tx-start DESCRIPTION

What it means

`ghidra trace tx-start` opens a manual transaction on the current trace and requires exactly one DESCRIPTION token. After the argument check, `STATE.require_no_tx()` runs, so an already-open transaction surfaces a different ('Transaction already started') error.

Source

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

    language, compiler = arch.compute_ghidra_lcsp()
    print(f"Selected Ghidra language: {language}")
    print(f"Selected Ghidra compiler: {compiler}")


@convert_errors
def ghidra_trace_txstart(debugger: lldb.SBDebugger, command: str,
                         result: lldb.SBCommandReturnObject,
                         internal_dict: Dict[str, Any]) -> None:
    """Start a transaction on the trace.

    Usage: ghidra trace tx-start DESCRIPTION
        DESCRIPTION must be in quotes if it contains spaces
    """

    args = shlex.split(command)
    if len(args) != 1:
        raise RuntimeError("Usage: ghidra trace tx-start DESCRIPTION")
    description = args[0]

    STATE.require_no_tx()
    STATE.tx = STATE.require_trace().start_tx(description, undoable=False)


@convert_errors
def ghidra_trace_txcommit(debugger: lldb.SBDebugger, command: str,
                          result: lldb.SBCommandReturnObject,
                          internal_dict: Dict[str, Any]) -> None:
    """Commit the current transaction.

    Usage: ghidra trace tx-commit
    """

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

View on GitHub (pinned to d5f144c24d)

Solutions

1. Provide one quoted description token: `ghidra trace tx-start "put memory"`
2. Ensure no transaction is already open before starting a new one

Example fix

// before
ghidra trace tx-start put memory
// after
ghidra trace tx-start "put memory"

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

try:
    ghidra_trace_txstart(debugger, command, result, internal_dict)
except RuntimeError as e:
    if str(e).startswith('Usage: ghidra trace tx-start'):
        # quote a multi-word description and retry
        ...
    raise

When it happens

Trigger: `ghidra trace tx-start` (no description); `ghidra trace tx-start put some memory` (an unquoted multi-word description becomes 3 tokens).

Common situations: Forgetting the description; a description with spaces not quoted so shlex splits it.

Related errors

• Usage: ghidra trace tx-commit
• Usage: ghidra trace tx-abort
• Usage: ghidra trace tx-open DESCRIPTION COMMAND
• Usage: ghidra trace connect ADDRESS
• ADDRESS must be HOST:PORT

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