{"record":{"id":"59ef83981452a6fa","repo":"NationalSecurityAgency/ghidra","slug":"address-must-be-port-or-host-port-59ef83","errorCode":null,"errorMessage":"address must be 'port' or 'host:port'","messagePattern":"address must be 'port' or 'host:port'","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-drgn/src/main/py/src/ghidradrgn/commands.py","lineNumber":191,"sourceCode":"def ghidra_trace_listen(address: str = '127.0.0.1:0') -> None:\n    \"\"\"\n    Listen for Ghidra to connect for tracing\n\n    Takes an optional address for the host and port on which to listen.\n    Either the form 'host:port' or just 'port'. If omitted, it will bind\n    to an ephemeral port on localhost. If only the port is given, it will\n    bind to that port on localhost. This command will block until the\n    connection is established.\n    \"\"\"\n\n    STATE.require_no_client()\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\n    try:\n        s = socket.socket()\n        s.bind((host, int(port)))\n        host, port = s.getsockname()\n        s.listen(1)\n        print(\"Listening at {}:{}...\".format(host, port))\n        c, (chost, cport) = s.accept()\n        s.close()\n        print(\"Connection from {}:{}\".format(chost, cport))\n        STATE.client = Client(c, \"drgn\", methods.REGISTRY)\n    except ValueError:\n        raise RuntimeError(\"port must be numeric\")\n\n\ndef ghidra_trace_disconnect() -> None:\n    \"\"\"Disconnect Python from Ghidra for tracing\"\"\"\n","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-drgn/src/main/py/src/ghidradrgn/commands.py#L173-L209","documentation":"Thrown by ghidra_trace_listen in the drgn agent when the address string, after splitting on ':', does not yield exactly 1 or 2 parts. A valid address is either a bare port ('12345') or 'host:port'. Three or more colons (or a leading/trailing colon producing an empty part in some cases) trigger this RuntimeError.","triggerScenarios":"Calling ghidra_trace_listen('::8080') (two colons, three parts), ghidra_trace_listen('a:b:c'), ghidra_trace_listen('host:port:extra'), or an address containing an IPv6-style address like '[::1]:8080' which splits into more than 2 parts on ':'.","commonSituations":"Passing an IPv6 address (which contains colons) without bracket notation; accidentally appending a path or extra segment to the address; empty address string that splits to [''] (1 part, but then port parse fails elsewhere); double separator '::' from a malformed config.","solutions":["Use the form 'port' (e.g. '12345') or 'host:port' (e.g. '127.0.0.1:12345') only.","For IPv6 localhost use the bracket-free numeric form '0:12345' is NOT valid — use '127.0.0.1:12345' since this parser does not support IPv6.","Check the address string does not contain more than one colon."],"exampleFix":"// before\nghidra_trace_listen('::1:8080')\n// after\nghidra_trace_listen('127.0.0.1:8080')","handlingStrategy":"validation","validationCode":"def validate_listen_address(address: str) -> None:\n    parts = address.split(':')\n    if len(parts) not in (1, 2):\n        raise ValueError(\n            f\"Address must be 'port' or 'host:port', got {len(parts)} parts: {address}\")\n\n# Call before ghidra_trace_listen:\nvalidate_listen_address(address)","typeGuard":null,"tryCatchPattern":"try:\n    ghidra_trace_listen(address)\nexcept RuntimeError as e:\n    if 'address must be' in str(e):\n        print(f\"Invalid listen address '{address}'. Use 'port' or 'host:port' only.\")\n    else:\n        raise","preventionTips":["Ensure the address string contains at most one colon.","Avoid IPv6 addresses — this parser does not support bracket notation.","Test the address with address.split(':') and assert len is 1 or 2 before calling."],"tags":["network","input-validation","drgn","address-parsing"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}