NationalSecurityAgency/ghidra · error · RuntimeError

port must be numeric

Error message

port must be numeric

What it means

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`.

Source

Thrown at Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py:293

    args = shlex.split(command)

    STATE.require_no_client()
    if len(args) != 1:
        raise RuntimeError("Usage: ghidra trace connect ADDRESS")
    address = args[0]

    parts = address.split(':')
    if len(parts) != 2:
        raise RuntimeError("ADDRESS must be HOST:PORT")
    host, port = parts
    try:
        c = socket.socket()
        c.connect((host, int(port)))
        STATE.client = Client(
            c, "lldb-" + util.LLDB_VERSION.full, methods.REGISTRY)
    except ValueError:
        raise RuntimeError("port must be numeric")


@convert_errors
def ghidra_trace_listen(debugger: lldb.SBDebugger, command: str,
                        result: lldb.SBCommandReturnObject,
                        internal_dict: Dict[str, Any]) -> None:
    """Listen for Ghidra to connect for tracing.

    Usage: ghidra trace listen [ADDRESS]
        ADDRESS must be PORT or HOST:PORT

    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.
    """

View on GitHub (pinned to d5f144c24d)

Solutions

1. Use a decimal integer port: `ghidra trace connect host:12345`
2. Resolve any service name to its decimal port number before passing it
3. Strip whitespace and stray characters from the port token

Example fix

// before
ghidra trace connect 127.0.0.1:http
// after
ghidra trace connect 127.0.0.1:80

def port_is_numeric(address: str) -> bool:
    parts = address.split(':')
    return len(parts) == 2 and parts[1].isdigit()

def is_int_port(s: str) -> bool:
    return s.isdigit() and 0 <= int(s) <= 65535

try:
    ghidra_trace_connect(debugger, address, result, internal_dict)
except RuntimeError as e:
    if str(e) == 'port must be numeric':
        # resolve the service name / strip the port and retry with a decimal port
        ...
    raise

When it happens

Trigger: `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.

Common situations: Using a service name (http, ssh) instead of a numeric port; copy-paste introducing a stray character; expecting hex or octal support.

Related errors

• Usage: ghidra trace connect ADDRESS
• ADDRESS must be HOST:PORT
• ADDRESS must be PORT or HOST:PORT
• Usage: ghidra trace listen [ADDRESS]
• PORT must be numeric

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