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:166-169) when the address argument is None. The function signature is address: Optional[str] = None, so calling it with no positional/keyword argument satisfies the type but fails the precondition that an address be supplied. require_no_client() runs first, so this only fires when there is no existing client.

Source

Thrown at Ghidra/Debug/Debugger-agent-x64dbg/src/main/py/src/ghidraxdbg/commands.py:168

        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, "x64dbg", 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 a host:port string, e.g. ghidra_trace_connect('127.0.0.1:12345').
2. If wrapping the command, require a non-empty address from the user before calling.
3. Use ghidra_trace_listen() instead if you want Ghidra to connect to the agent rather than the agent connecting out.

Example fix

// before
ghidra_trace_connect()

// after
ghidra_trace_connect('127.0.0.1:12345')

def connect(address=None):
    if not address:
        raise ValueError('address is required (host:port)')
    ghidra_trace_connect(address)

def has_address(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):
        address = prompt_user('host:port')
        ghidra_trace_connect(address)
    else:
        raise

When it happens

Trigger: Invoking ghidra_trace_connect() with no argument at all, or explicitly ghidra_trace_connect(address=None). Occurs when the command is dispatched from a UI/script that forwards no parameter.

Common situations: A menu item or wrapper script wired to the command without binding an address field; mistaking the Optional default for a 'connect to default' behavior; a bridge that passes None when the user left the field blank.

Related errors

• address must be in the form 'host:port'
• port must be numeric
• Invalid argument: {key_list[0]}
• Transaction already started
• address must be 'port' or 'host:port'

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