{"record":{"id":"3e3f9636f0ee495e","repo":"NationalSecurityAgency/ghidra","slug":"port-must-be-numeric-3e3f96","errorCode":null,"errorMessage":"port must be numeric","messagePattern":"port must be numeric","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":293,"sourceCode":"\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\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","sourceCodeStart":275,"sourceCodeEnd":311,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L275-L311","documentation":"Once host and port are split, `int(port)` is attempted inside the socket-connect try block; a non-integer port raises ValueError, re-raised as this message. Only the port portion is validated — the host is passed straight to `socket.connect`.","triggerScenarios":"`ghidra trace connect host:abc`; `ghidra trace connect host:12.34`; `ghidra trace connect host:0x1F` (hex is not parsed by int); a port token with a trailing non-numeric character.","commonSituations":"Using a service name (http, ssh) instead of a numeric port; copy-paste introducing a stray character; expecting hex or octal support.","solutions":["Use a decimal integer port: `ghidra trace connect host:12345`","Resolve any service name to its decimal port number before passing it","Strip whitespace and stray characters from the port token"],"exampleFix":"// before\nghidra trace connect 127.0.0.1:http\n// after\nghidra trace connect 127.0.0.1:80","handlingStrategy":"validation","validationCode":"def port_is_numeric(address: str) -> bool:\n    parts = address.split(':')\n    return len(parts) == 2 and parts[1].isdigit()","typeGuard":"def is_int_port(s: str) -> bool:\n    return s.isdigit() and 0 <= int(s) <= 65535","tryCatchPattern":"try:\n    ghidra_trace_connect(debugger, address, result, internal_dict)\nexcept RuntimeError as e:\n    if str(e) == 'port must be numeric':\n        # resolve the service name / strip the port and retry with a decimal port\n        ...\n    raise","preventionTips":["Pass a decimal integer port, never a service name or hex","Resolve service names to numbers before invoking","Strip whitespace from the port token before passing"],"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"}