NationalSecurityAgency/ghidra · error · RuntimeError

'ghidra_trace_connect': missing required argument 'address'

Error message

'ghidra_trace_connect': missing required argument 'address'

What it means

Raised by ghidra_trace_connect() (commands.py:170-172) when the address argument is None. Although the signature defaults address to None for command-shell ergonomics, a real connection requires an explicit host:port target. This is a usage contract check before any socket work begins.

Source

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

        if self.tx != None:
            raise RuntimeError("Transaction already started")

    def reset_tx(self) -> None:
        self.tx: Optional[Transaction] = None


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.

View on GitHub (pinned to d5f144c24d)

Solutions

1. Pass an explicit 'host:port' string, e.g. ghidra_trace_connect('127.0.0.1:12345').
2. If the value comes from a config/env var, validate it is non-empty before calling (see validationCode).
3. When integrating from a UI, surface a 'Connect address required' prompt instead of calling with None.

Example fix

// before
ghidra_trace_connect()      # missing arg

// after
ghidra_trace_connect('127.0.0.1:12345')

def safe_connect(address):
    if not address:
        raise ValueError('address is required, e.g. 127.0.0.1:12345')
    ghidra_trace_connect(address)

def is_address_present(address) -> bool:
    return isinstance(address, str) and bool(address.strip())

try:
    ghidra_trace_connect(address)
except RuntimeError as e:
    if 'missing required argument' in str(e):
        raise ValueError('caller must supply host:port') from e
    raise

When it happens

Trigger: Invoking 'ghidra_trace_connect' in the dbgeng/cdb command interpreter with no argument; calling ghidra_trace_connect(None) from Python; a wrapper that forgot to forward the address parameter.

Common situations: User typed the bare command name in WinDbg/cdb expecting a prompt; Python integration that conditionally passes address and accidentally passed None; script template that left address blank.

Related errors

• address must be in the form 'host:port'
• port must be numeric
• address must be 'port' or 'host:port'
• Not connected
• Already connected

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