NationalSecurityAgency/ghidra · error · RuntimeError

address must be in the form 'host:port'

Error message

address must be in the form 'host:port'

What it means

Raised as RuntimeError by ghidra_trace_connect() when address.split(':') does not yield exactly two parts. The connect command only accepts the strict 'host:port' form (single colon) — bare ports, IPv6, or extra colons are rejected.

Source

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

STATE = State()


def ghidra_trace_connect(address: Optional[str] = None) -> None:
    """
    Connect Python to Ghidra for tracing

    Address must be of the form 'host:port'
    """

    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

View on GitHub (pinned to d5f144c24d)

Solutions

1. Provide the address strictly as 'host:port' (single colon), e.g. '127.0.0.1:12345'.
2. For port-only input, prepend '127.0.0.1:' or use ghidra_trace_listen instead.
3. Normalize/strip the address and validate it has exactly one colon before calling.

Example fix

// before
ghidra_trace_connect('12345')       # one part -> RuntimeError
ghidra_trace_connect('host:p:1')    # three parts -> RuntimeError
// after
ghidra_trace_connect('127.0.0.1:12345')

parts = address.split(':')
if len(parts) != 2 or not parts[0] or not parts[1]:
    raise RuntimeError("address must be 'host:port' (single colon)")
ghidra_trace_connect(address)

import re
_HOST_PORT = re.compile(r'^[^:]+:[0-9]+$')
def is_host_port(address) -> bool:
    return isinstance(address, str) and bool(_HOST_PORT.match(address))

try:
    ghidra_trace_connect(address)
except RuntimeError as e:
    if 'host:port' in str(e):
        ghidra_trace_connect('127.0.0.1:' + str(address))  # port-only fixup
    else:
        raise

When it happens

Trigger: Passing a port-only string ('12345'), an IPv6 literal ('::1:12345'), an empty string, or a value with multiple/no colons to ghidra_trace_connect().

Common situations: User enters just a port (should use ghidra_trace_listen or supply host); copy-pasting an IPv6 address; trailing whitespace/colons in the address.

Related errors

• 'ghidra_trace_connect': missing required argument 'address'
• address must be in the form 'host:port'
• port must be numeric
• address must be 'port' or 'host:port'
• Not connected

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