{"record":{"id":"d03725a8abdbbce3","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-new-snap-snap-description","errorCode":null,"errorMessage":"Usage: ghidra trace new-snap [SNAP] DESCRIPTION","messagePattern":"Usage: ghidra trace new-snap \\[SNAP\\] DESCRIPTION","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":634,"sourceCode":"def ghidra_trace_new_snap(debugger: lldb.SBDebugger, command: str,\n                          result: lldb.SBCommandReturnObject,\n                          internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Create a new snapshot.\n\n    Usage: ghidra trace new-snap [SNAP] DESCRIPTION\n\n    Subsequent modifications to machine state will affect the new snapshot.\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) == 1:\n        time = None\n        description = args[0]\n    elif len(args) == 2:\n        time = Schedule(int(args[0]))\n        description = args[1]\n    else:\n        raise RuntimeError(\"Usage: ghidra trace new-snap [SNAP] DESCRIPTION\")\n    STATE.require_trace().snapshot(description, time=time)\n\n\ndef quantize_pages(start: int, end: int) -> Tuple[int, int]:\n    return (start // PAGE_SIZE * PAGE_SIZE, (end+PAGE_SIZE-1) // PAGE_SIZE*PAGE_SIZE)\n\n\ndef check_count(actual: int, requested: int):\n    if actual != requested: \n        print(f\"Incomplete read: {actual} bytes\")\n    \n\ndef put_bytes(start: int, end: int, result: lldb.SBCommandReturnObject,\n              pages: bool) -> None:\n    trace = STATE.require_trace()\n    if pages:\n        start, end = quantize_pages(start, end)\n    proc = util.get_process()","sourceCodeStart":616,"sourceCodeEnd":652,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L616-L652","documentation":"`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.","triggerScenarios":"`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).","commonSituations":"Forgetting the description; a multi-word description not quoted; expecting SNAP and DESCRIPTION to both be independently optional.","solutions":["Provide a description, optionally preceded by a SNAP: `ghidra trace new-snap \"after breakpoint\"` or `ghidra trace new-snap 5 \"after breakpoint\"`","Quote multi-word descriptions so the total token count is 1 or 2"],"exampleFix":"// before\nghidra trace new-snap after breakpoint\n// after\nghidra trace new-snap \"after breakpoint\"","handlingStrategy":"validation","validationCode":"import shlex\ndef one_or_two_args(command: str) -> bool:\n    return len(shlex.split(command)) in (1, 2)","typeGuard":null,"tryCatchPattern":"try:\n    ghidra_trace_new_snap(debugger, command, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e).startswith('Usage: ghidra trace new-snap'):\n        # quote the description (and optional leading SNAP) and retry\n        ...\n    raise","preventionTips":["Always supply a DESCRIPTION; it is required","Quote multi-word descriptions so the token count is 1 or 2","Remember a lone number is treated as the DESCRIPTION, not the SNAP"],"tags":["ghidra","lldb","cli","validation","trace","snapshot"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}