NationalSecurityAgency/ghidra · error · RuntimeError

port must be numeric

Error message

port must be numeric

What it means

Thrown by ghidra_trace_connect in the drgn agent when the port component of the 'host:port' address string cannot be parsed as an integer. The ValueError from int(port) (or from socket.connect) is caught and re-raised as RuntimeError with this message. This guards the socket connection attempt so a meaningful error reaches the user rather than a raw ValueError traceback.

Source

Thrown at Ghidra/Debug/Debugger-agent-drgn/src/main/py/src/ghidradrgn/commands.py:170

    """

    STATE.require_no_client()
    if address is None:
        raise RuntimeError(
            "'ghidra_trace_connect': missing required argument 'address'")

    parts = address.split(':')
    if len(parts) != 2:
        raise RuntimeError("address must be in the form 'host:port'")
    host, port = parts
    try:
        c = socket.socket()
        c.connect((host, int(port)))
        # TODO: Can we get version info from the DLL?
        STATE.client = Client(c, "drgn", methods.REGISTRY)
        print(f"Connected to {STATE.client.description} at {address}")
    except ValueError:
        raise RuntimeError("port must be numeric")


def ghidra_trace_listen(address: str = '127.0.0.1:0') -> None:
    """
    Listen for Ghidra to connect for tracing

    Takes an optional address for the host and port on which to listen.
    Either the form 'host:port' or just 'port'. If omitted, it will bind
    to an ephemeral port on localhost. If only the port is given, it will
    bind to that port on localhost. This command will block until the
    connection is established.
    """

    STATE.require_no_client()
    parts = address.split(':')
    if len(parts) == 1:
        host, port = '127.0.0.1', parts[0]
    elif len(parts) == 2:

View on GitHub (pinned to d5f144c24d)

Solutions

1. Ensure the port is a plain base-10 integer in the range 0-65535, e.g. '127.0.0.1:12345'.
2. Strip any protocol prefix (http://, tcp://) and trailing whitespace from the address string before passing it.
3. Validate the port substring with int(port_str) in a try/except before calling ghidra_trace_connect.

Example fix

// before
ghidra_trace_connect('localhost:ssh')
// after
ghidra_trace_connect('localhost:22')

def validate_connect_address(address: str) -> None:
    parts = address.split(':')
    if len(parts) != 2:
        raise ValueError(f"Address must be 'host:port', got: {address}")
    host, port = parts
    try:
        p = int(port)
        if not (0 <= p <= 65535):
            raise ValueError(f"Port out of range: {p}")
    except ValueError:
        raise ValueError(f"Port must be numeric (0-65535), got: {port}")

# Call before ghidra_trace_connect:
validate_connect_address(address)

try:
    ghidra_trace_connect(address)
except RuntimeError as e:
    if 'port must be numeric' in str(e):
        print(f"Invalid port in address '{address}'. Use 'host:port' with a numeric port.")
    else:
        raise

When it happens

Trigger: Calling ghidra_trace_connect('host:abc'), ghidra_trace_connect('127.0.0.1:notaport'), or any address where the substring after the colon is not a base-10 integer. Also fires if the port contains whitespace, a protocol prefix like 'tcp://', or a service name like 'http'.

Common situations: Typo in the port string when copy-pasting an address; accidentally including a URL scheme (e.g. 'tcp://host:1234'); using a service name instead of a numeric port; trailing whitespace or newline in a port read from a config file.

Related errors

• address must be 'port' or 'host:port'
• Cannot convert '{}' to length
• Invalid argument: {arg}
• Address {address} is not in process {proc}
• Invalid byte_order: {}

AI-assisted analysis of NationalSecurityAgency/ghidra@d5f144c24d (2026-08-14). Data as JSON: /api/errors/9844158864b88b96. Report an issue: GitHub.