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.

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 HOST:PORT
• address must be in the form 'host:port'
• address must be 'port' or 'host:port'
• ADDRESS must be PORT or HOST:PORT

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

Appendix: 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)