{"record":{"id":"ebb7a153360bc426","repo":"NationalSecurityAgency/ghidra","slug":"usage-ghidra-trace-putval-expression-pages","errorCode":null,"errorMessage":"Usage: ghidra trace putval EXPRESSION [PAGES]","messagePattern":"Usage: ghidra trace putval EXPRESSION \\[PAGES\\]","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py","lineNumber":766,"sourceCode":"    or its address is not in memory, an error results.\n\n    Please note, register and value aliases, e.g., '$pc' or '$1' may be assigned\n    to a temporary memory address by LLDB. Thus, a command like\n\n       ghidra trace putval $1\n\n    may result in undefined behavior.\n    \"\"\"\n\n    args = shlex.split(command)\n    if len(args) == 1:\n        expression = args[0]\n        pages = True\n    elif len(args) == 2:\n        expression = args[0]\n        pages = (util.get_eval(args[2]).unsigned != 0)\n    else:\n        raise RuntimeError(\"Usage: ghidra trace putval EXPRESSION [PAGES]\")\n\n    STATE.require_tx()\n    try:\n        value = util.get_eval(expression)\n        address = value.addr\n    except BaseException as e:\n        raise RuntimeError(f\"Could not evaluate {expression}: {e}\")\n    if not address.IsValid():\n        raise RuntimeError(f\"Expression {expression} does not have an address\")\n    start = int(address)\n    end = start + start + value.size\n    return put_bytes(start, end, result, pages)\n\n\ndef putmem_state(address: str, length: str, state: str,\n                 pages: bool = True) -> None:\n    trace = STATE.require_trace()\n    trace.validate_state(state)","sourceCodeStart":748,"sourceCodeEnd":784,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Debugger-agent-lldb/src/main/py/src/ghidralldb/commands.py#L748-L784","documentation":"Usage error raised by ghidra_trace_putval when the token count is not 1 or 2. putval records the bytes of an EXPRESSION's value into the trace, with an optional second PAGES flag. NOTE: the source has a latent bug on line 764 (pages = util.get_eval(args[2]) while only args[0..1] exist), so the 2-arg path itself can IndexError before this message is reached in some builds.","triggerScenarios":"Calling 'ghidra trace putval' with zero tokens or 3+ tokens. Separately, a call with exactly 2 tokens may instead throw IndexError at args[2] because the code reads the wrong array slot for PAGES.","commonSituations":"User adds a --pages flag (unsupported); user passes both a value and a length; user wraps the expression in extra quotes producing unexpected splits.","solutions":["Pass exactly one token (EXPRESSION) or two tokens (EXPRESSION PAGES).","For PAGES, pass a positional 0/1 expression like '1' or '0', not a flag.","If the 2-arg form crashes with IndexError on args[2], patch commands.py line 764 to use args[1] (this is a code bug, not user error)."],"exampleFix":"// before\nghidra trace putval myvar --pages\n// after\nghidra trace putval myvar 1","handlingStrategy":"validation","validationCode":"import shlex\n\ndef validate_putval(command: str) -> None:\n    n = len(shlex.split(command))\n    if n not in (1, 2):\n        raise ValueError('ghidra trace putval needs EXPRESSION [PAGES]')\n    # NOTE: even when n==2, source reads args[2] (a bug); prefer n==1 to be safe.\n    if n == 2:\n        import warnings\n        warnings.warn('putval 2-arg form has an args[2] indexing bug; pass EXPRESSION only.')","typeGuard":null,"tryCatchPattern":"try:\n    ghidra_trace_putval(debugger, command, result, internal_dict)\nexcept (RuntimeError, IndexError) as e:\n    result.SetError(f'putval failed ({type(e).__name__}): {e}')","preventionTips":["Pass EXPRESSION only; avoid the buggy 2-arg PAGES form until commands.py line 764 is fixed.","Validate token count client-side before invoking.","Patch line 764 to use args[1] if you control the agent source."],"tags":["ghidra-trace","argument-validation","cli-usage","known-bug"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}