NationalSecurityAgency/ghidra · error · RuntimeError

port must be numeric

Error message

port must be numeric

What it means

Raised by ghidra_trace_connect (commands.py:181-182) from the except ValueError clause wrapping int(port). The split produced two parts (so the form check passed) but the port token is not a base-10 integer, so int(port) raises ValueError which is converted into this RuntimeError.

Source

Thrown at Ghidra/Debug/Debugger-agent-x64dbg/src/main/py/src/ghidraxdbg/commands.py:182

    """

    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, "x64dbg", 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:
        host, port = parts

View on GitHub (pinned to d5f144c24d)

Solutions

1. Use a decimal integer port, e.g. '127.0.0.1:12345'.
2. Strip whitespace and validate isdigit() on the port token before calling.
3. Convert hex input to decimal first if the source is hexadecimal.

Example fix

// before
ghidra_trace_connect('127.0.0.1:0x50')

// after
ghidra_trace_connect('127.0.0.1:80')

host, _, port = address.rpartition(':')
if not port.isdigit():
    raise ValueError(f'port must be numeric, got {port!r}')
ghidra_trace_connect(f'{host}:{int(port)}')

def port_is_numeric(address: str) -> bool:
    port = address.rpartition(':')[2]
    return port.isdigit()

try:
    ghidra_trace_connect(address)
except RuntimeError as e:
    if 'port must be numeric' in str(e):
        raise ValueError(f'Please enter a numeric port in {address}') from e
    raise

When it happens

Trigger: Calling ghidra_trace_connect('host:abc'), 'host:0x80' (hex not accepted by int base 10), 'host:' (empty port), or 'host:12.5' (non-integer).

Common situations: User enters a service name instead of a port number; copies a hex offset; trailing whitespace in the port token; a port field that allowed free text.

Related errors

• 'ghidra_trace_connect': missing required argument 'address'
• address must be in the form 'host:port'
• address must be 'port' or 'host:port'
• Invalid argument: {key_list[0]}
• Address {address} is not in process {proc}

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