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 by ghidra_trace_connect() (commands.py:174-176) when the address string does not split into exactly two colon-separated parts. The connect command requires the strict 'host:port' form (unlike listen, which also accepts a bare port). Any address with zero, two, or more than one colon is rejected.

Source

Thrown at Ghidra/Debug/Debugger-agent-dbgeng/src/main/py/src/ghidradbg/commands.py:176

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, "dbgeng.dll", 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

View on GitHub (pinned to d5f144c24d)

Solutions

1. Provide exactly 'host:port' with a single colon, e.g. '127.0.0.1:12345'.
2. For IPv6, use the listen side or wrap the literal so it contains no extra colon, or connect by IPv4/hostname.
3. If you only have a port, call ghidra_trace_listen(port) instead.

Example fix

// before
ghidra_trace_connect('12345')          # one part
ghidra_trace_connect('[::1]:12345')     # three parts after split

// after
ghidra_trace_connect('127.0.0.1:12345')
# or, if you only have a port, listen instead:
ghidra_trace_listen('12345')

def validate_host_port(address):
    parts = address.split(':')
    if len(parts) != 2 or not parts[0] or not parts[1]:
        raise ValueError("address must be 'host:port' with exactly one colon")
    return parts

host, port = validate_host_port(address)
ghidra_trace_connect(address)

def is_host_port(address) -> bool:
    if not isinstance(address, str):
        return False
    parts = address.split(':')
    return len(parts) == 2 and bool(parts[0]) and bool(parts[1])

try:
    ghidra_trace_connect(address)
except RuntimeError as e:
    if 'must be in the form' in str(e):
        raise ValueError(f'fix address to host:port: {address!r}') from e
    raise

When it happens

Trigger: Passing '12345' (port only — not accepted by connect, use listen instead); passing '[::1]:12345' or any IPv6 literal (multiple colons); passing 'host only' with no colon; passing 'host:port:extra'.

Common situations: User pasted an IPv6 address; user expected connect to accept a bare port like listen does; trailing whitespace or a typo removing the colon.

Related errors

• port must be numeric
• address must be 'port' or 'host:port'
• 'ghidra_trace_connect': missing required argument 'address'
• Usage: ghidra trace connect ADDRESS
• ADDRESS must be HOST:PORT

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