What causes "Usage: ghidra trace put-regions" in NationalSecurityAgency/ghidra?

Invoke bare: `ghidra trace put-regions`.

NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace put-regions

Error message

Usage: ghidra trace put-regions

What it means

Raised by ghidra_trace_put_regions when any argument is supplied. put-regions reads the target's memory map (where supported) and writes Regions into the trace; it is parameterless (commands.py:1763). Some targets don't support regions, handled separately in should_query_regions.

Source

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

        regobj.set_value('Offset', hex(r.offset))
        regobj.set_value('Object File', r.objfile)
        regobj.insert()
    trace.proxy_object_path(
        MEMORY_PATTERN.format(procnum=proc.GetProcessID())).retain_values(keys)


@convert_errors
def ghidra_trace_put_regions(debugger: lldb.SBDebugger, command: str,
                             result: lldb.SBCommandReturnObject,
                             internal_dict: Dict[str, Any]) -> None:
    """Read the memory map, if applicable, and write to the trace's Regions.

    Usage: ghidra trace put-regions
    """

    args = shlex.split(command)
    if len(args) != 0:
        raise RuntimeError("Usage: ghidra trace put-regions")

    trace, tx = STATE.require_tx()
    with trace.client.batch() as b:
        put_regions()


def put_modules() -> None:
    target = util.get_target()
    proc = util.get_process()
    modules = util.MODULE_INFO_READER.get_modules()
    trace = STATE.require_trace()
    mapper = trace.extra.require_mm()
    mod_keys = []
    for mk, m in modules.items():
        mpath = MODULE_PATTERN.format(procnum=proc.GetProcessID(), modpath=mk)
        modobj = trace.create_object(mpath)
        mod_keys.append(MODULE_KEY_PATTERN.format(modpath=mk))
        modobj.set_value('Name', m.name)

View on GitHub (pinned to d5f144c24d)

Solutions

Invoke bare: `ghidra trace put-regions`.
If regions come back empty, check should_query_regions() / LLDB gdb-remote region bug, not command arguments.

Example fix

// before
ghidra trace put-regions stack
// after
ghidra trace put-regions

Defensive patterns

Strategy: validation

Validate before calling

assert len(command.split()) == 0, "put-regions takes no arguments"

Prevention

put-regions publishes the whole memory map — no region filter.
If regions are empty, investigate target/protocol support, not args.

When it happens

Trigger: Appending a region name, address range, or filter token, e.g. `ghidra trace put-regions 0x1000`, or stray text.

Common situations: Users want to publish a single region or filter unmapped areas and pass a selector. The command always publishes the whole memory map for the current process.

Related errors

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