{"record":{"id":"d06fbb51dc2fbf15","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-create-obj-path","errorCode":null,"errorMessage":"Usage: ghidra trace create-obj PATH","messagePattern":"Usage: ghidra trace create-obj PATH","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":992,"sourceCode":"@convert_errors\ndef ghidra_trace_create_obj(debugger: lldb.SBDebugger, command: str,\n                            result: lldb.SBCommandReturnObject,\n                            internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Create an object in the Ghidra trace.\n\n    Usage: ghidra trace create-obj PATH\n\n    PATH gives the objects fully-qualified name, e.g., Processes[0].Threads[1],\n    which often denotes the second thread of the first target process.\n\n    The new object is in a detached state, so it may not be immediately\n    recognized by the Debugger GUI. Use 'ghidra trace insert-obj' to finish the\n    object, after all its required attributes are set.\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) != 1:\n        raise RuntimeError(\"Usage: ghidra trace create-obj PATH\")\n    path = args[0]\n\n    trace, tx = STATE.require_tx()\n    obj = trace.create_object(path)\n    obj.insert()\n    result.PutCString(f\"Created object: id={obj.id}, path='{obj.path}'\")\n\n\n@convert_errors\ndef ghidra_trace_insert_obj(debugger: lldb.SBDebugger, command: str,\n                            result: lldb.SBCommandReturnObject,\n                            internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Insert an object into the Ghidra trace.\n\n    Usage: ghidra trace insert-obj PATH\n\n    See 'ghidra trace create-obj'. An object in a detached state is missing\n    some or all of its ancestry for its lifespan. Inserting the object creates","sourceCodeStart":974,"sourceCodeEnd":1010,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L974-L1010","documentation":"Usage error raised by ghidra_trace_create_obj when the token count is not exactly 1. create_obj needs a single fully-qualified object PATH (e.g. Processes[0].Threads[1]); the new object is created in a detached state and later inserted with insert-obj.","triggerScenarios":"Passing zero paths or a multi-token path that was not quoted; passing additional flags; whitespace inside an unquoted path.","commonSituations":"User forgets to quote a path containing brackets/spaces; user tries to create several objects at once; user passes options.","solutions":["Pass exactly one PATH token.","If the path contains characters shlex would split on, wrap the entire command so PATH stays one token.","Use canonical indexed path syntax like Processes[0].Memory[]."],"exampleFix":"// before\nghidra trace create-obj Processes[0] Threads[1]\n// after\nghidra trace create-obj Processes[0].Threads[1]","handlingStrategy":"validation","validationCode":"import shlex\n\ndef validate_create_obj(command: str) -> None:\n    if len(shlex.split(command)) != 1:\n        raise ValueError('create-obj needs exactly one PATH token')","typeGuard":"def is_single_path_token(command: str) -> bool:\n    return len(shlex.split(command)) == 1","tryCatchPattern":"try:\n    ghidra_trace_create_obj(debugger, command, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e).startswith('Usage:'):\n        result.SetError(str(e))\n    else:\n        raise","preventionTips":["Quote bracketed paths so they remain one token.","Follow create-obj with insert-obj to make the object visible.","Use canonical indexed path syntax."],"tags":["ghidra-trace","argument-validation","object-tree","cli-usage"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}