{"record":{"id":"0899d04e67067d8b","repo":"NationalSecurityAgency/ghidra","slug":"port-must-be-numeric","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-dbgeng/src/main/py/src/ghidradbg/commands.py","lineNumber":185,"sourceCode":"    \"\"\"\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\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","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-dbgeng/src/main/py/src/ghidradbg/commands.py#L167-L203","documentation":"Raised by ghidra_trace_connect() (commands.py:184-185) when int(port) raises ValueError after the host:port split succeeded. The host part passed shape validation but the port token is not a base-10 integer.","triggerScenarios":"Passing 'host:abc', 'host:12.5', 'host:-' or any non-numeric port; port containing trailing whitespace or a unit like '8080/tcp'; empty port string 'host:'.","commonSituations":"Config sourced the port from an env var as a float string; copy/paste that included '/tcp' suffix; locale/formatting artifacts in the port field.","solutions":["Strip the port and ensure it is a plain decimal integer in 0..65535.","Validate port with int(port) in a guard before calling connect (see validationCode).","Remove any '/protocol' suffix or whitespace from the value."],"exampleFix":"// before\nghidra_trace_connect('127.0.0.1:8080/tcp')   # ValueError -> port must be numeric\n\n// after\nport = '8080/tcp'.split('/')[0].strip()\nghidra_trace_connect(f'127.0.0.1:{int(port)}')","handlingStrategy":"validation","validationCode":"def parse_port(token):\n    try:\n        p = int(token)\n    except (TypeError, ValueError):\n        raise ValueError(f'port must be numeric, got {token!r}')\n    if not 0 <= p <= 65535:\n        raise ValueError('port out of range')\n    return p\n\nhost, port = address.split(':')\nparse_port(port)   # raises before connect if invalid","typeGuard":"def port_is_numeric(token) -> bool:\n    try:\n        return 0 <= int(token) <= 65535\n    except (TypeError, ValueError):\n        return False","tryCatchPattern":"try:\n    ghidra_trace_connect(address)\nexcept RuntimeError as e:\n    if 'port must be numeric' in str(e):\n        raise ValueError('strip non-numeric suffixes from the port') from e\n    raise","preventionTips":["Strip '/tcp', whitespace, and signs from port strings.","Range-check the port (0..65535) in your config loader.","Treat ports as integers end-to-end in your pipeline."],"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"}