{"record":{"id":"953fec0736b7321b","repo":"NationalSecurityAgency/ghidra","slug":"address-must-be-in-the-form-host-port-953fec","errorCode":null,"errorMessage":"address must be in the form 'host:port'","messagePattern":"address must be in the form 'host:port'","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-x64dbg/src/main/py/src/ghidraxdbg/commands.py","lineNumber":173,"sourceCode":"\n\nSTATE = State()\n\n\ndef ghidra_trace_connect(address: Optional[str] = None) -> None:\n    \"\"\"Connect Python to Ghidra for tracing.\n\n    Address must be of the form 'host:port'\n    \"\"\"\n\n    STATE.require_no_client()\n    if address is None:\n        raise RuntimeError(\n            \"'ghidra_trace_connect': missing required argument 'address'\")\n\n    parts = address.split(':')\n    if len(parts) != 2:\n        raise RuntimeError(\"address must be in the form 'host:port'\")\n    host, port = parts\n    try:\n        c = socket.socket()\n        c.connect((host, int(port)))\n        # TODO: Can we get version info from the DLL?\n        STATE.client = Client(c, \"x64dbg\", methods.REGISTRY)\n        print(f\"Connected to {STATE.client.description} at {address}\")\n    except ValueError:\n        raise RuntimeError(\"port must be numeric\")\n\n\ndef ghidra_trace_listen(address: str = '127.0.0.1:0') -> None:\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","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-x64dbg/src/main/py/src/ghidraxdbg/commands.py#L155-L191","documentation":"Raised by ghidra_trace_connect (commands.py:171-173) when address.split(':') does not yield exactly two parts. Unlike ghidra_trace_listen, connect requires the strict two-part host:port form; a bare port or an address with two or more colons is rejected.","triggerScenarios":"Calling ghidra_trace_connect('8080') (port only, 1 part), ghidra_trace_connect('localhost') (1 part), ghidra_trace_connect('a:b:c') (3 parts), or an IPv6-style address with multiple colons.","commonSituations":"User copies a port-only value intended for listen into connect; passing an IPv6 literal (e.g. '[::1]:8080' splits to more than 2 on a naive split); trailing/leading colons producing empty parts.","solutions":["Provide exactly one colon separating host and port, e.g. '127.0.0.1:12345'.","For a port-only input, prepend the host: ghidra_trace_connect(f'127.0.0.1:{port}').","For IPv6, supply an explicit host that splits to exactly two tokens or normalize before calling."],"exampleFix":"// before\nghidra_trace_connect('8080')\n\n// after\nghidra_trace_connect('127.0.0.1:8080')","handlingStrategy":"validation","validationCode":"def normalize_connect_address(s: str) -> str:\n    parts = s.split(':')\n    if len(parts) == 1:\n        return f'127.0.0.1:{parts[0]}'\n    if len(parts) != 2:\n        raise ValueError(f\"address must be host:port, got {s!r}\")\n    return s\n\nghidra_trace_connect(normalize_connect_address(raw))","typeGuard":"def is_host_port(s: str) -> bool:\n    return isinstance(s, str) and len(s.split(':')) == 2","tryCatchPattern":"try:\n    ghidra_trace_connect(address)\nexcept RuntimeError as e:\n    if 'form' in str(e):\n        address = f'127.0.0.1:{address}'\n        ghidra_trace_connect(address)\n    else:\n        raise","preventionTips":["Validate the colon count before calling.","Auto-prefix 127.0.0.1: for port-only input if the intent is localhost.","Reject IPv6 literals or normalize them before split(':')."],"tags":["connect","argument-validation","address-parsing","python"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}