{"record":{"id":"6d568d6329fab56b","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-tx-start-description","errorCode":null,"errorMessage":"Usage: ghidra trace tx-start DESCRIPTION","messagePattern":"Usage: ghidra trace tx-start DESCRIPTION","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":522,"sourceCode":"\n    language, compiler = arch.compute_ghidra_lcsp()\n    print(f\"Selected Ghidra language: {language}\")\n    print(f\"Selected Ghidra compiler: {compiler}\")\n\n\n@convert_errors\ndef ghidra_trace_txstart(debugger: lldb.SBDebugger, command: str,\n                         result: lldb.SBCommandReturnObject,\n                         internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Start a transaction on the trace.\n\n    Usage: ghidra trace tx-start DESCRIPTION\n        DESCRIPTION must be in quotes if it contains spaces\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) != 1:\n        raise RuntimeError(\"Usage: ghidra trace tx-start DESCRIPTION\")\n    description = args[0]\n\n    STATE.require_no_tx()\n    STATE.tx = STATE.require_trace().start_tx(description, undoable=False)\n\n\n@convert_errors\ndef ghidra_trace_txcommit(debugger: lldb.SBDebugger, command: str,\n                          result: lldb.SBCommandReturnObject,\n                          internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Commit the current transaction.\n\n    Usage: ghidra trace tx-commit\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) != 0:\n        raise RuntimeError(\"Usage: ghidra trace tx-commit\")","sourceCodeStart":504,"sourceCodeEnd":540,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L504-L540","documentation":"`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.","triggerScenarios":"`ghidra trace tx-start` (no description); `ghidra trace tx-start put some memory` (an unquoted multi-word description becomes 3 tokens).","commonSituations":"Forgetting the description; a description with spaces not quoted so shlex splits it.","solutions":["Provide one quoted description token: `ghidra trace tx-start \"put memory\"`","Ensure no transaction is already open before starting a new one"],"exampleFix":"// before\nghidra trace tx-start put memory\n// after\nghidra trace tx-start \"put memory\"","handlingStrategy":"validation","validationCode":"import shlex\ndef exactly_one_arg(command: str) -> bool:\n    return len(shlex.split(command)) == 1","typeGuard":null,"tryCatchPattern":"try:\n    ghidra_trace_txstart(debugger, command, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e).startswith('Usage: ghidra trace tx-start'):\n        # quote a multi-word description and retry\n        ...\n    raise","preventionTips":["Quote multi-word descriptions so they form a single token","Confirm no transaction is already open before tx-start","Prefer `ghidra trace tx-open` for single put commands over manual tx-start/commit"],"tags":["ghidra","lldb","cli","validation","transaction"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}