NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace listen [ADDRESS]

Error message

Usage: ghidra trace listen [ADDRESS]

What it means

`ghidra trace listen` takes at most one whitespace-separated argument. Passing two or more tokens raises this before any address parsing or socket work.

Source

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

    connection is established.
    """

    args = shlex.split(command)
    host: str
    port: Union[str, int]
    if len(args) == 0:
        host, port = '127.0.0.1', 0
    elif len(args) == 1:
        address = args[0]
        parts = address.split(':')
        if len(parts) == 1:
            host, port = '127.0.0.1', parts[0]
        elif len(parts) == 2:
            host, port = parts
        else:
            raise RuntimeError("ADDRESS must be PORT or HOST:PORT")
    else:
        raise RuntimeError("Usage: ghidra trace listen [ADDRESS]")

    STATE.require_no_client()
    try:
        s = socket.socket()
        s.bind((host, int(port)))
        host, port = s.getsockname()
        s.listen(1)
        print(f"Listening at {host}:{port}...")
        c, (chost, cport) = s.accept()
        s.close()
        print(f"Connection from {chost}:{cport}")
        STATE.client = Client(
            c, util.LLDB_VERSION.display, methods.REGISTRY)
    except ValueError:
        raise RuntimeError("PORT must be numeric")


@convert_errors

View on GitHub (pinned to d5f144c24d)

Solutions

1. Combine host and port into one token: `ghidra trace listen 127.0.0.1:8080`
2. Or pass only the port and accept the default loopback host: `ghidra trace listen 8080`

Example fix

// before
ghidra trace listen 127.0.0.1 8080
// after
ghidra trace listen 127.0.0.1:8080

import shlex
def single_listen_arg(command: str) -> bool:
    return len(shlex.split(command)) <= 1

try:
    ghidra_trace_listen(debugger, command, result, internal_dict)
except RuntimeError as e:
    if str(e).startswith('Usage: ghidra trace listen'):
        # collapse host+port into one HOST:PORT token and retry
        ...
    raise

When it happens

Trigger: `ghidra trace listen 127.0.0.1 8080` (host and port as separate tokens); `ghidra trace listen host port extra`.

Common situations: Passing host and port as two arguments (a space instead of the required colon); appending flags this command does not support.

Related errors

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

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