{"record":{"id":"322a06734761283a","repo":"NationalSecurityAgency/ghidra","slug":"address-must-be-host-port","errorCode":null,"errorMessage":"ADDRESS must be HOST:PORT","messagePattern":"ADDRESS must be HOST:PORT","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":285,"sourceCode":"                         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,\n                        internal_dict: Dict[str, Any]) -> None:\n    \"\"\"Listen for Ghidra to connect for tracing.\n\n    Usage: ghidra trace listen [ADDRESS]\n        ADDRESS must be PORT or HOST:PORT","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L267-L303","documentation":"After confirming exactly one address token, connect splits it on `:` and requires exactly two parts. A token with no colon (bare host or port) or with more than one colon (e.g. a raw IPv6 literal like `::1:1234`) fails here. This agent does not accept bracketed IPv6 notation on this path.","triggerScenarios":"`ghidra trace connect 12345` (port only); `ghidra trace connect localhost` (host only); `ghidra trace connect ::1:1234` (IPv6 yields 3 parts); `ghidra trace connect 127.0.0.1:1234:extra`.","commonSituations":"Forgetting the host: prefix; pasting an IPv6 address without realizing the colon count breaks the split; a doubled or missing separator from retyping.","solutions":["Always use the HOST:PORT form: `ghidra trace connect 127.0.0.1:12345`","For IPv6, this code path cannot parse it — use an IPv4 address or a resolvable hostname instead","Verify there is exactly one colon separating host and port"],"exampleFix":"// before\nghidra trace connect 12345\n// after\nghidra trace connect 127.0.0.1:12345","handlingStrategy":"validation","validationCode":"import re\nHOST_PORT = re.compile(r'^[^:]+:[0-9]+$')\n\ndef is_host_port(s: str) -> bool:\n    return bool(HOST_PORT.match(s)) and len(s.split(':')) == 2","typeGuard":"import re\nfrom typing import Tuple\n\ndef parse_host_port(s: str) -> Tuple[str, str] | None:\n    parts = s.split(':')\n    if len(parts) != 2 or not parts[1].isdigit():\n        return None\n    return parts[0], parts[1]","tryCatchPattern":"try:\n    ghidra_trace_connect(debugger, address, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e) == 'ADDRESS must be HOST:PORT':\n        # reformat address to exactly one host:port token\n        ...\n    raise","preventionTips":["Ensure exactly one colon separates host and port","Do not pass raw IPv6 literals to this command; use IPv4 or a hostname","Validate the token shape before invoking the command"],"tags":["network","ghidra","lldb","cli","validation","connection","ipv6"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}