NationalSecurityAgency/ghidra · error · KeyError

No such register: {name}

Error message

No such register: {name}

What it means

Raised by find_reg_by_name when iterating util.get_register_descs(frame.architecture()) finds no descriptor whose name matches the requested register name (case-insensitive). The GDB Python API lacks a get-register-by-name method, so the agent scans the architecture's descriptor list; an unknown/aliased/unsupported register name leaves the loop empty. KeyError signals 'No such register: name'.

Source

Thrown at Ghidra/Debug/Debugger-agent-gdb/src/main/py/src/ghidragdb/methods.py:231

def find_frame_by_obj(object: TraceObject) -> Optional[gdb.Frame]:
    return find_frame_by_pattern(FRAME_PATTERN, object, "a StackFrame")


def find_frame_by_regs_obj(object: TraceObject) -> Optional[gdb.Frame]:
    return find_frame_by_pattern(REGS_PATTERN, object,
                                 "a RegisterValueContainer")


# Because there's no method to get a register by name....
def find_reg_by_name(f: gdb.Frame, name: str) -> Union[gdb.RegisterDescriptor,
                                                       util.RegisterDesc]:
    for reg in util.get_register_descs(f.architecture()):
        # TODO: gdb appears to be case sensitive, but until we encounter a
        # situation where case matters, we'll be insensitive
        if reg.name.lower() == name.lower():
            return reg
    raise KeyError(f"No such register: {name}")


# Oof. no gdb/Python method to get breakpoint by number
# I could keep my own cache in a dict, but why?
def find_bpt_by_number(breaknum: int) -> gdb.Breakpoint:
    # TODO: If len exceeds some threshold, use binary search?
    for b in gdb.breakpoints():
        if b.number == breaknum:
            return b
    raise KeyError(f"Breakpoints[{breaknum}] does not exist")


def find_bpt_by_pattern(pattern: re.Pattern, object: TraceObject,
                        err_msg: str) -> gdb.Breakpoint:
    mat = pattern.fullmatch(object.path)
    if mat is None:
        raise TypeError(f"{object} is not {err_msg}")
    breaknum = int(mat['breaknum'])

View on GitHub (pinned to d5f144c24d)

Solutions

  1. Enumerate the available register names for the architecture and validate membership before lookup.
  2. Map client register names through an arch-specific alias table before calling find_reg_by_name.
  3. In the caller, catch KeyError and return an empty/'unsupported register' result to the client rather than crashing.
  4. Confirm frame.architecture() is set (not None) before enumerating descriptors.

Example fix

// before
reg = find_reg_by_name(f, name)
// after
avail = {r.name.lower() for r in util.get_register_descs(f.architecture())}
if name.lower() not in avail:
    return None  # or raise a client-facing 'unknown register'
reg = find_reg_by_name(f, name)
Defensive patterns

Strategy: validation

Validate before calling

avail = {r.name.lower() for r in util.get_register_descs(f.architecture())}
if name.lower() not in avail:
    return None  # unknown register for this arch
reg = find_reg_by_name(f, name)

Type guard

def register_known(f: gdb.Frame, name: str) -> bool:
    return any(r.name.lower() == name.lower()
               for r in util.get_register_descs(f.architecture()))

Try / catch

try:
    reg = find_reg_by_name(f, name)
except KeyError:
    # unknown register; map via alias table or return empty
    return None

Prevention

When it happens

Trigger: Calling find_reg_by_name with a register name not present on the current frame's architecture — e.g. requesting 'rax' on ARM, a vendor/alias name GDB does not expose, or a name from a different ABI. Reached via register read/write method handlers that accept a client-supplied register name.

Common situations: Client (Ghidra UI) requests a register name valid on a different architecture; cross-architecture sessions where the trace's language differs from the target; alias/sub-register names not enumerated by gdb.RegisterDescriptor; version differences in GDB's register descriptor enumeration.

Related errors

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