NationalSecurityAgency/ghidra · error · RuntimeError

PORT must be numeric

Error message

PORT must be numeric

What it means

During listen, `s.bind((host, int(port)))` converts the port to an integer; a non-numeric port raises ValueError, re-raised as this message. The message casing ('PORT must be numeric') differs from connect's, so it identifies the listen path specifically.

Source

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

        else:
            raise RuntimeError("ADDRESS must be PORT or HOST:PORT")
    else:
        raise RuntimeError("Usage: ghidra trace listen [ADDRESS]")

    STATE.require_no_client()
    try:
        s = socket.socket()
        s.bind((host, int(port)))
        host, port = s.getsockname()
        s.listen(1)
        print(f"Listening at {host}:{port}...")
        c, (chost, cport) = s.accept()
        s.close()
        print(f"Connection from {chost}:{cport}")
        STATE.client = Client(
            c, util.LLDB_VERSION.display, methods.REGISTRY)
    except ValueError:
        raise RuntimeError("PORT must be numeric")


@convert_errors
def ghidra_trace_disconnect(debugger: lldb.SBDebugger, command: str,
                            result: lldb.SBCommandReturnObject,
                            internal_dict: Dict[str, Any]) -> None:
    """Disconnect LLDB from Ghidra for tracing.

    Usage: ghidra trace disconnect
    """

    args = shlex.split(command)
    if len(args) != 0:
        raise RuntimeError("Usage: ghidra trace disconnect")

    STATE.require_client().close()
    STATE.reset_client()

View on GitHub (pinned to d5f144c24d)

Solutions

  1. Use a decimal port: `ghidra trace listen 8080`
  2. Resolve service names to integers before passing them

Example fix

// before
ghidra trace listen http
// after
ghidra trace listen 80
Defensive patterns

Strategy: validation

Validate before calling

def listen_port_is_numeric(token: str) -> bool:
    parts = token.split(':')
    port = parts[-1]
    return port.isdigit()

Type guard

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

Try / catch

try:
    ghidra_trace_listen(debugger, token, result, internal_dict)
except RuntimeError as e:
    if str(e) == 'PORT must be numeric':
        # replace service name / non-numeric port with a decimal port
        ...
    raise

Prevention

When it happens

Trigger: `ghidra trace listen abc`; `ghidra trace listen host:xyz`; `ghidra trace listen 80.5`.

Common situations: Using a service name instead of a numeric port; a stray character in the port token.

Related errors

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