{"record":{"id":"c10b40699a392ad7","repo":"NationalSecurityAgency/ghidra","slug":"ghidra-trace-connect-missing-required-argument","errorCode":null,"errorMessage":"'ghidra_trace_connect': missing required argument 'address'","messagePattern":"'ghidra_trace_connect': missing required argument 'address'","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-dbgeng/src/main/py/src/ghidradbg/commands.py","lineNumber":171,"sourceCode":"        if self.tx != None:\n            raise RuntimeError(\"Transaction already started\")\n\n    def reset_tx(self) -> None:\n        self.tx: Optional[Transaction] = None\n\n\nSTATE = State()\n\n\ndef ghidra_trace_connect(address: Optional[str] = None) -> None:\n    \"\"\"Connect Python to Ghidra for tracing.\n\n    Address must be of the form 'host:port'\n    \"\"\"\n\n    STATE.require_no_client()\n    if address is None:\n        raise RuntimeError(\n            \"'ghidra_trace_connect': missing required argument 'address'\")\n\n    parts = address.split(':')\n    if len(parts) != 2:\n        raise RuntimeError(\"address must be in the form 'host:port'\")\n    host, port = parts\n    try:\n        c = socket.socket()\n        c.connect((host, int(port)))\n        # TODO: Can we get version info from the DLL?\n        STATE.client = Client(c, \"dbgeng.dll\", methods.REGISTRY)\n        print(f\"Connected to {STATE.client.description} at {address}\")\n    except ValueError:\n        raise RuntimeError(\"port must be numeric\")\n\n\ndef ghidra_trace_listen(address: str = '127.0.0.1:0') -> None:\n    \"\"\"Listen for Ghidra to connect for tracing.","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-dbgeng/src/main/py/src/ghidradbg/commands.py#L153-L189","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass an explicit 'host:port' string, e.g. ghidra_trace_connect('127.0.0.1:12345').","If the value comes from a config/env var, validate it is non-empty before calling (see validationCode).","When integrating from a UI, surface a 'Connect address required' prompt instead of calling with None."],"exampleFix":"// before\nghidra_trace_connect()      # missing arg\n\n// after\nghidra_trace_connect('127.0.0.1:12345')","handlingStrategy":"validation","validationCode":"def safe_connect(address):\n    if not address:\n        raise ValueError('address is required, e.g. 127.0.0.1:12345')\n    ghidra_trace_connect(address)","typeGuard":"def is_address_present(address) -> bool:\n    return isinstance(address, str) and bool(address.strip())","tryCatchPattern":"try:\n    ghidra_trace_connect(address)\nexcept RuntimeError as e:\n    if 'missing required argument' in str(e):\n        raise ValueError('caller must supply host:port') from e\n    raise","preventionTips":["Make the address parameter required in your wrapper.","Source host:port from a single validated config value.","Fail fast in your UI if the field is empty."],"tags":["usage","connection","debugger-agent","ghidra"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}