{"record":{"id":"8e15d890f4b5cad9","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-connect-address","errorCode":null,"errorMessage":"Usage: ghidra trace connect ADDRESS","messagePattern":"Usage: ghidra trace connect ADDRESS","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":280,"sourceCode":"\n\n@convert_errors\ndef ghidra_trace_connect(debugger: lldb.SBDebugger, command: str,\n                         result: lldb.SBCommandReturnObject,\n                         internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Connect LLDB to Ghidra for tracing.\n\n    Usage: ghidra trace connect ADDRESS\n        ADDRESS must be HOST:PORT\n\n    The required address must be of the form 'host:port'\n    \"\"\"\n\n    args = shlex.split(command)\n\n    STATE.require_no_client()\n    if len(args) != 1:\n        raise RuntimeError(\"Usage: ghidra trace connect ADDRESS\")\n    address = args[0]\n\n    parts = address.split(':')\n    if len(parts) != 2:\n        raise RuntimeError(\"ADDRESS must be HOST:PORT\")\n    host, port = parts\n    try:\n        c = socket.socket()\n        c.connect((host, int(port)))\n        STATE.client = Client(\n            c, \"lldb-\" + util.LLDB_VERSION.full, methods.REGISTRY)\n    except ValueError:\n        raise RuntimeError(\"port must be numeric\")\n\n\n@convert_errors\ndef ghidra_trace_listen(debugger: lldb.SBDebugger, command: str,\n                        result: lldb.SBCommandReturnObject,","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L262-L298","documentation":"Thrown by the `ghidra trace connect` command when `shlex.split(command)` does not produce exactly one token. The command needs a single ADDRESS of the form HOST:PORT so it can open a TCP socket to Ghidra's trace-RMI server, so any other token count aborts before a socket is created. Note `STATE.require_no_client()` runs first, so an already-connected session surfaces a different ('Already connected') error.","triggerScenarios":"`ghidra trace connect` with no address; `ghidra trace connect 127.0.0.1 12345` (host and port as two tokens); `ghidra trace connect my host:1234` where an unquoted space makes shlex split into two tokens.","commonSituations":"Copy-pasting a command but dropping the address; assuming host and port are separate arguments like `connect` in some other tools; pasting a hostname containing a space without quotes.","solutions":["Provide a single HOST:PORT token: `ghidra trace connect 127.0.0.1:12345`","If any token could contain a space, quote the whole argument so shlex yields exactly one token","Run `ghidra trace info` first to confirm you are not already connected, since require_no_client is checked before this usage check"],"exampleFix":"// before\nghidra trace connect 127.0.0.1 12345\n// after\nghidra trace connect 127.0.0.1:12345","handlingStrategy":"validation","validationCode":"import shlex\n\ndef valid_connect_cmd(command: str) -> bool:\n    tokens = shlex.split(command)\n    return len(tokens) == 1 and len(tokens[0].split(':')) == 2\n\n# before running:\nassert valid_connect_cmd('ghidra trace connect 127.0.0.1:12345')","typeGuard":null,"tryCatchPattern":"# only relevant if calling the Python function directly / scripting around it\ntry:\n    ghidra_trace_connect(debugger, '127.0.0.1:12345', result, internal_dict)\nexcept RuntimeError as e:\n    if str(e).startswith('Usage: ghidra trace connect'):\n        # fix the argument shape and retry\n        ...\n    raise","preventionTips":["Always pass host and port joined by a colon in a single token","Quote any argument that might contain a space","Run `ghidra trace info` to check connection state before connecting"],"tags":["network","ghidra","lldb","cli","validation","connection"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}