NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace connect ADDRESS

Error message

Usage: ghidra trace connect ADDRESS

What it means

Thrown by the `ghidra trace connect` command when `shlex.split(command)` does not produce exactly one token. The command needs a single ADDRESS of the form HOST:PORT so it can open a TCP socket to Ghidra's trace-RMI server, so any other token count aborts before a socket is created. Note `STATE.require_no_client()` runs first, so an already-connected session surfaces a different ('Already connected') error.

Source

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

@convert_errors
def ghidra_trace_connect(debugger: lldb.SBDebugger, command: str,
                         result: lldb.SBCommandReturnObject,
                         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,

View on GitHub (pinned to d5f144c24d)

Solutions

1. Provide a single HOST:PORT token: `ghidra trace connect 127.0.0.1:12345`
2. If any token could contain a space, quote the whole argument so shlex yields exactly one token
3. Run `ghidra trace info` first to confirm you are not already connected, since require_no_client is checked before this usage check

Example fix

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

import shlex

def valid_connect_cmd(command: str) -> bool:
    tokens = shlex.split(command)
    return len(tokens) == 1 and len(tokens[0].split(':')) == 2

# before running:
assert valid_connect_cmd('ghidra trace connect 127.0.0.1:12345')

# only relevant if calling the Python function directly / scripting around it
try:
    ghidra_trace_connect(debugger, '127.0.0.1:12345', result, internal_dict)
except RuntimeError as e:
    if str(e).startswith('Usage: ghidra trace connect'):
        # fix the argument shape and retry
        ...
    raise

When it happens

Trigger: `ghidra trace connect` with no address; `ghidra trace connect 127.0.0.1 12345` (host and port as two tokens); `ghidra trace connect my host:1234` where an unquoted space makes shlex split into two tokens.

Common situations: Copy-pasting a command but dropping the address; assuming host and port are separate arguments like `connect` in some other tools; pasting a hostname containing a space without quotes.

Related errors

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

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