NationalSecurityAgency/ghidra · error · RuntimeError

Usage: ghidra trace putmem ADDRESS LENGTH [PAGES]

Error message

Usage: ghidra trace putmem ADDRESS LENGTH [PAGES]

What it means

Usage error raised by ghidra_trace_putmem when shlex.split(command) yields neither 2 nor 3 tokens. The command requires ADDRESS and LENGTH, with an optional third PAGES flag; any other arity is rejected before STATE.require_tx() is touched.

Source

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

    Writes the given range of bytes from memory into the Ghidra trace. ADDRESS
    is a memory address. It is expression evaluated within the current target.
    LENGTH is the number of bytes to write, also evaluated within the current
    target. PAGES is a boolean value. If true, the range will be quantized to
    page boundaries that include the requested range.
    """

    args = shlex.split(command)
    if len(args) == 2:
        address = args[0]
        length = args[1]
        pages = True
    elif len(args) == 3:
        address = args[0]
        length = args[1]
        pages = (util.get_eval(args[2]).unsigned != 0)
    else:
        raise RuntimeError("Usage: ghidra trace putmem ADDRESS LENGTH [PAGES]")

    STATE.require_tx()
    putmem(address, length, result, pages)


@convert_errors
def ghidra_trace_putval(debugger: lldb.SBDebugger, command: str,
                        result: lldb.SBCommandReturnObject,
                        internal_dict: Dict[str, Any]) -> None:
    """Record the given value into the Ghidra trace, if it's in memory.

    Usage: ghidra trace putval EXPRESSION [PAGES]

    Evaluates the given expression within the current target. If the resulting
    value has an address in the target's memory, the bytes comprising that value
    are written into the Ghidra trace. If PAGES is true, then the full page(s)
    containing those bytes are written. If the resulting value has no address,
    or its address is not in memory, an error results.

View on GitHub (pinned to d5f144c24d)

Solutions

1. Supply exactly two or three tokens: ADDRESS LENGTH [PAGES].
2. If ADDRESS or LENGTH contains spaces/special chars, ensure they are a single LLDB expression token (quote the whole command if needed).
3. Remember PAGES is a positional 0/1 expression, not a --pages flag.

Example fix

// before
ghidra trace putmem 0x10000
// after
ghidra trace putmem 0x10000 0x100

import shlex

def validate_putmem(command: str) -> None:
    n = len(shlex.split(command))
    if n not in (2, 3):
        raise ValueError('ghidra trace putmem needs ADDRESS LENGTH [PAGES]')

try:
    ghidra_trace_putmem(debugger, command, result, internal_dict)
except RuntimeError as e:
    if str(e).startswith('Usage:'):
        result.SetError('Syntax: ' + str(e))
    else:
        raise

When it happens

Trigger: Running 'ghidra trace putmem' with 0, 1, or 4+ tokens; forgetting LENGTH; passing extra unquoted spaces; quoting mistakes that collapse or inflate the token count.

Common situations: New users omit LENGTH thinking the command auto-sizes; users copy-paste a path with spaces that shlex splits into many tokens; passing flags like '-pages' that are not supported (PAGES is positional).

Related errors

• Usage: ghidra trace putval EXPRESSION [PAGES]
• Usage: ghidra trace putmem ADDRESS LENGTH STATE [PAGES]
• Usage: ghidra trace delmem ADDRESS LENGTH
• Usage: ghidra trace putreg [GROUP]
• Usage: ghidra trace delreg [GROUP]

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