{"record":{"id":"dc3df7009f5910e7","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-listen-address","errorCode":null,"errorMessage":"Usage: ghidra trace listen [ADDRESS]","messagePattern":"Usage: ghidra trace listen \\[ADDRESS\\]","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":327,"sourceCode":"    connection is established.\n    \"\"\"\n\n    args = shlex.split(command)\n    host: str\n    port: Union[str, int]\n    if len(args) == 0:\n        host, port = '127.0.0.1', 0\n    elif len(args) == 1:\n        address = args[0]\n        parts = address.split(':')\n        if len(parts) == 1:\n            host, port = '127.0.0.1', parts[0]\n        elif len(parts) == 2:\n            host, port = parts\n        else:\n            raise RuntimeError(\"ADDRESS must be PORT or HOST:PORT\")\n    else:\n        raise RuntimeError(\"Usage: ghidra trace listen [ADDRESS]\")\n\n    STATE.require_no_client()\n    try:\n        s = socket.socket()\n        s.bind((host, int(port)))\n        host, port = s.getsockname()\n        s.listen(1)\n        print(f\"Listening at {host}:{port}...\")\n        c, (chost, cport) = s.accept()\n        s.close()\n        print(f\"Connection from {chost}:{cport}\")\n        STATE.client = Client(\n            c, util.LLDB_VERSION.display, methods.REGISTRY)\n    except ValueError:\n        raise RuntimeError(\"PORT must be numeric\")\n\n\n@convert_errors","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L309-L345","documentation":"`ghidra trace listen` takes at most one whitespace-separated argument. Passing two or more tokens raises this before any address parsing or socket work.","triggerScenarios":"`ghidra trace listen 127.0.0.1 8080` (host and port as separate tokens); `ghidra trace listen host port extra`.","commonSituations":"Passing host and port as two arguments (a space instead of the required colon); appending flags this command does not support.","solutions":["Combine host and port into one token: `ghidra trace listen 127.0.0.1:8080`","Or pass only the port and accept the default loopback host: `ghidra trace listen 8080`"],"exampleFix":"// before\nghidra trace listen 127.0.0.1 8080\n// after\nghidra trace listen 127.0.0.1:8080","handlingStrategy":"validation","validationCode":"import shlex\ndef single_listen_arg(command: str) -> bool:\n    return len(shlex.split(command)) <= 1","typeGuard":null,"tryCatchPattern":"try:\n    ghidra_trace_listen(debugger, command, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e).startswith('Usage: ghidra trace listen'):\n        # collapse host+port into one HOST:PORT token and retry\n        ...\n    raise","preventionTips":["Pass host and port joined by a colon, not separated by a space","Provide at most one argument to listen","Omit the host entirely to listen on loopback with just a port"],"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"}