{"record":{"id":"cb38bd2a5c446c48","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-insert-obj-path","errorCode":null,"errorMessage":"Usage: ghidra trace insert-obj PATH","messagePattern":"Usage: ghidra trace insert-obj PATH","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":1016,"sourceCode":"    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\n    its ancestry for its whole lifespan.\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) != 1:\n        raise RuntimeError(\"Usage: ghidra trace insert-obj PATH\")\n    path = args[0]\n\n    # NOTE: id parameter is probably not necessary, since this command is for\n    # humans.\n    trace, tx = STATE.require_tx()\n    span = trace.proxy_object_path(path).insert()\n    result.PutCString(f\"Inserted object: lifespan={span}\")\n\n\n@convert_errors\ndef ghidra_trace_remove_obj(debugger: lldb.SBDebugger, command: str,\n                            result: lldb.SBCommandReturnObject,\n                            internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Remove an object from the Ghidra trace.\n\n    Usage: ghidra trace remove-obj PATH\n\n    This does not delete the object. It just removes it from the tree for the","sourceCodeStart":998,"sourceCodeEnd":1034,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L998-L1034","documentation":"Usage error raised by ghidra_trace_insert_obj when the token count is not exactly 1. insert_obj finishes a detached object by creating its ancestry across the object's lifespan; it requires the single PATH previously passed to create-obj.","triggerScenarios":"Zero tokens; multi-token path; trailing flags; mismatched PATH between create and insert.","commonSituations":"User forgets to quote a bracketed path; user runs insert-obj before create-obj; user passes extra arguments.","solutions":["Pass exactly one PATH token matching the one used in create-obj.","Quote the command so the bracketed PATH is a single token.","Ensure create-obj was called for that PATH first."],"exampleFix":"// before\nghidra trace insert-obj Processes[0] Threads[1]\n// after\nghidra trace insert-obj Processes[0].Threads[1]","handlingStrategy":"validation","validationCode":"import shlex\n\ndef validate_insert_obj(command: str) -> None:\n    if len(shlex.split(command)) != 1:\n        raise ValueError('insert-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_insert_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":["Match the PATH used in create-obj.","Quote bracketed paths.","Create the object before inserting it."],"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"}