{"record":{"id":"83178096e2f3a701","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-start-name","errorCode":null,"errorMessage":"Usage: ghidra trace start [NAME]","messagePattern":"Usage: ghidra trace start \\[NAME\\]","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":412,"sourceCode":"@convert_errors\ndef ghidra_trace_start(debugger: lldb.SBDebugger, command: str,\n                       result: lldb.SBCommandReturnObject,\n                       internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Start a Trace in Ghidra.\n\n    Usage: ghidra trace start [NAME]\n\n    Takes an optional name for the trace. If omitted, it tries to derive the\n    name from the target image.\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) == 0:\n        name = compute_name()\n    elif len(args) == 1:\n        name = args[0]\n    else:\n        raise RuntimeError(\"Usage: ghidra trace start [NAME]\")\n\n    STATE.require_client()\n    STATE.require_no_trace()\n    start_trace(name)\n\n\n@convert_errors\ndef ghidra_trace_stop(debugger: lldb.SBDebugger, command: str,\n                      result: lldb.SBCommandReturnObject,\n                      internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Stop the Trace in Ghidra.\n\n    Usage: ghidra trace stop\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) != 0:\n        raise RuntimeError(\"Usage: ghidra trace stop\")","sourceCodeStart":394,"sourceCodeEnd":430,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L394-L430","documentation":"`ghidra trace start` accepts 0 arguments (the name is auto-derived from the target image via `compute_name`) or 1 argument (an explicit name). Two or more tokens abort before `require_client`/`require_no_trace` run.","triggerScenarios":"`ghidra trace start my trace` (an unquoted name with a space becomes two tokens); `ghidra trace start a b`.","commonSituations":"A trace name containing spaces passed without quotes, so shlex splits it into multiple tokens.","solutions":["Quote a multi-word name: `ghidra trace start \"my trace\"`","Or omit the name to auto-derive it from the target image: `ghidra trace start`"],"exampleFix":"// before\nghidra trace start my trace\n// after\nghidra trace start \"my trace\"","handlingStrategy":"validation","validationCode":"import shlex\ndef zero_or_one_arg(command: str) -> bool:\n    return len(shlex.split(command)) <= 1","typeGuard":null,"tryCatchPattern":"try:\n    ghidra_trace_start(debugger, command, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e).startswith('Usage: ghidra trace start'):\n        # quote a multi-word name or drop extra tokens and retry\n        ...\n    raise","preventionTips":["Quote multi-word trace names","Omit the name to let it derive from the target image","Confirm a client connection and no active trace before starting"],"tags":["ghidra","lldb","cli","validation","trace"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}