NationalSecurityAgency/ghidra · error · RuntimeError

ADDRESS must be HOST:PORT

Error message

ADDRESS must be HOST:PORT

What it means

After confirming exactly one address token, connect splits it on `:` and requires exactly two parts. A token with no colon (bare host or port) or with more than one colon (e.g. a raw IPv6 literal like `::1:1234`) fails here. This agent does not accept bracketed IPv6 notation on this path.

Source

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

                         internal_dict: Dict[str, Any]) -> None:
    """Connect LLDB to Ghidra for tracing.

    Usage: ghidra trace connect ADDRESS
        ADDRESS must be HOST:PORT

    The required address must be of the form 'host:port'
    """

    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

View on GitHub (pinned to d5f144c24d)

Solutions

1. Always use the HOST:PORT form: `ghidra trace connect 127.0.0.1:12345`
2. For IPv6, this code path cannot parse it — use an IPv4 address or a resolvable hostname instead
3. Verify there is exactly one colon separating host and port

Example fix

// before
ghidra trace connect 12345
// after
ghidra trace connect 127.0.0.1:12345

import re
HOST_PORT = re.compile(r'^[^:]+:[0-9]+$')

def is_host_port(s: str) -> bool:
    return bool(HOST_PORT.match(s)) and len(s.split(':')) == 2

import re
from typing import Tuple

def parse_host_port(s: str) -> Tuple[str, str] | None:
    parts = s.split(':')
    if len(parts) != 2 or not parts[1].isdigit():
        return None
    return parts[0], parts[1]

try:
    ghidra_trace_connect(debugger, address, result, internal_dict)
except RuntimeError as e:
    if str(e) == 'ADDRESS must be HOST:PORT':
        # reformat address to exactly one host:port token
        ...
    raise

When it happens

Trigger: `ghidra trace connect 12345` (port only); `ghidra trace connect localhost` (host only); `ghidra trace connect ::1:1234` (IPv6 yields 3 parts); `ghidra trace connect 127.0.0.1:1234:extra`.

Common situations: Forgetting the host: prefix; pasting an IPv6 address without realizing the colon count breaks the split; a doubled or missing separator from retyping.

Related errors

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

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