{"record":{"id":"532808d996df9ba2","repo":"NationalSecurityAgency/ghidra","slug":"address-must-be-in-the-form-host-port","errorCode":null,"errorMessage":"address must be in the form 'host:port'","messagePattern":"address must be in the form 'host:port'","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-dbgeng/src/main/py/src/ghidradbg/commands.py","lineNumber":176,"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, \"dbgeng.dll\", 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":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-dbgeng/src/main/py/src/ghidradbg/commands.py#L158-L194","documentation":"Raised by ghidra_trace_connect() (commands.py:174-176) when the address string does not split into exactly two colon-separated parts. The connect command requires the strict 'host:port' form (unlike listen, which also accepts a bare port). Any address with zero, two, or more than one colon is rejected.","triggerScenarios":"Passing '12345' (port only — not accepted by connect, use listen instead); passing '[::1]:12345' or any IPv6 literal (multiple colons); passing 'host only' with no colon; passing 'host:port:extra'.","commonSituations":"User pasted an IPv6 address; user expected connect to accept a bare port like listen does; trailing whitespace or a typo removing the colon.","solutions":["Provide exactly 'host:port' with a single colon, e.g. '127.0.0.1:12345'.","For IPv6, use the listen side or wrap the literal so it contains no extra colon, or connect by IPv4/hostname.","If you only have a port, call ghidra_trace_listen(port) instead."],"exampleFix":"// before\nghidra_trace_connect('12345')          # one part\nghidra_trace_connect('[::1]:12345')     # three parts after split\n\n// after\nghidra_trace_connect('127.0.0.1:12345')\n# or, if you only have a port, listen instead:\nghidra_trace_listen('12345')","handlingStrategy":"validation","validationCode":"def validate_host_port(address):\n    parts = address.split(':')\n    if len(parts) != 2 or not parts[0] or not parts[1]:\n        raise ValueError(\"address must be 'host:port' with exactly one colon\")\n    return parts\n\nhost, port = validate_host_port(address)\nghidra_trace_connect(address)","typeGuard":"def is_host_port(address) -> bool:\n    if not isinstance(address, str):\n        return False\n    parts = address.split(':')\n    return len(parts) == 2 and bool(parts[0]) and bool(parts[1])","tryCatchPattern":"try:\n    ghidra_trace_connect(address)\nexcept RuntimeError as e:\n    if 'must be in the form' in str(e):\n        raise ValueError(f'fix address to host:port: {address!r}') from e\n    raise","preventionTips":["Avoid IPv6 literals for connect (use a hostname or IPv4).","Validate host:port shape before calling.","Use listen() if you only have a port."],"tags":["usage","connection","validation","ghidra"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}