NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace tx-open DESCRIPTION COMMAND

Error message

Usage: ghidra trace tx-open DESCRIPTION COMMAND

What it means

`ghidra trace tx-open` requires exactly two tokens: a DESCRIPTION and a COMMAND to run inside an open transaction. It is the recommended wrapper around one or more `put` commands. Fewer or more than two tokens aborts.

Source

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

    STATE.reset_tx()


@convert_errors
def ghidra_trace_txopen(debugger: lldb.SBDebugger, command: str,
                        result: lldb.SBCommandReturnObject,
                        internal_dict: Dict[str, Any]) -> None:
    """Run a command with an open transaction.

    Usage: ghidra trace tx-open DESCRIPTION COMMAND

    Execute the given command with an open transaction. This is generally
    useful only when executing a single 'put' command, or when executing a
    custom command that performs several puts.
    """

    args = shlex.split(command)
    if len(args) != 2:
        raise RuntimeError("Usage: ghidra trace tx-open DESCRIPTION COMMAND")

    description = args[0]
    cmd = args[1]
    with open_tracked_tx(description):
        lldb.debugger.GetCommandInterpreter().HandleCommand(cmd, result)


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

    Usage: ghidra trace save
    """

    args = shlex.split(command)
    if len(args) != 0:

View on GitHub (pinned to d5f144c24d)

Solutions

1. Pass exactly two tokens, quoting any that contain spaces: `ghidra trace tx-open "put memory" "ghidra trace putmem 0x1000 0x10"`
2. Keep the COMMAND to a single subcommand, or wrap a multi-step put sequence in one quoted string

Example fix

// before
ghidra trace tx-open putmem 0x1000 0x10
// after
ghidra trace tx-open "put mem" "ghidra trace putmem 0x1000 0x10"

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

try:
    ghidra_trace_txopen(debugger, command, result, internal_dict)
except RuntimeError as e:
    if str(e).startswith('Usage: ghidra trace tx-open'):
        # quote the description and/or the embedded command and retry
        ...
    raise

When it happens

Trigger: Only one token (description omitted); three or more tokens because the COMMAND or DESCRIPTION contained spaces and was not quoted; e.g. `ghidra trace tx-open putmem 0x1000 0x10` (the COMMAND was not quoted so it splits).

Common situations: Passing a multi-word subcommand without quotes; omitting the description.

Related errors

• Usage: ghidra trace tx-start DESCRIPTION
• Usage: ghidra trace tx-commit
• Usage: ghidra trace tx-abort
• 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/b8c897e3e5a07da8. Report an issue: GitHub.