NationalSecurityAgency/ghidra · error · KeyError

Events[{eventnum}] does not exist

Error message

Events[{eventnum}] does not exist

What it means

Raised by find_evt_by_number() (methods.py:203-204) as a KeyError when util.GetSpecificFilterParameters(eventnum, 1) raises E_NOINTERFACE_Error — dbgeng has no specific event filter at that index. dbgeng distinguishes specific filters (indexed) from arbitrary exception filters; this lookup is for the specific-filter table only.

Source

Thrown at Ghidra/Debug/Debugger-agent-dbgeng/src/main/py/src/ghidradbg/methods.py:204

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


def find_bpt_by_obj(object: TraceObject) -> DbgEng.IDebugBreakpoint:
    return find_bpt_by_pattern(PROC_BREAKBPT_PATTERN, object, "a BreakpointSpec")


def find_evt_by_number(eventnum: int) -> DbgEng._DEBUG_SPECIFIC_FILTER_PARAMETERS:
    try:
        return util.GetSpecificFilterParameters(eventnum, 1)
    except exception.E_NOINTERFACE_Error:
        raise KeyError(f"Events[{eventnum}] does not exist")


def find_evt_by_pattern(pattern: re.Pattern, object: TraceObject,
                        err_msg: str) -> DbgEng._DEBUG_SPECIFIC_FILTER_PARAMETERS:
    mat = pattern.fullmatch(object.path)
    if mat is None:
        raise TypeError(f"{object} is not {err_msg}")
    eventnum = int(mat['eventnum'])
    return (eventnum, find_evt_by_number(eventnum))


def find_evt_cont_by_obj(object: TraceObject) -> DbgEng._DEBUG_SPECIFIC_FILTER_PARAMETERS:
    return find_evt_by_pattern(PROC_EVENT_CONT_PATTERN, object, "as Event")


def find_evt_exec_by_obj(object: TraceObject) -> DbgEng._DEBUG_SPECIFIC_FILTER_PARAMETERS:
    return find_evt_by_pattern(PROC_EVENT_EXEC_PATTERN, object, "as Event")

View on GitHub (pinned to d5f144c24d)

Solutions

  1. Query the current specific-filter count (GetNumberEventFilters) and confirm eventnum is in range before lookup.
  2. Distinguish specific filters (Events[n]) from exception filters (Exceptions[n]) — they use separate index spaces and separate find_*_by_number functions.
  3. Wrap in try/except KeyError if a missing filter is a recoverable condition.

Example fix

// before
params = find_evt_by_number(stale_index)   # KeyError: Events[5] does not exist

// after
n_specific = util.GetNumberEventFilters()[1]   # specific-filter count
if 0 <= stale_index < n_specific:
    params = find_evt_by_number(stale_index)
else:
    # handle missing filter
    pass
Defensive patterns

Strategy: try-catch

Validate before calling

def event_filter_exists(eventnum) -> bool:
    try:
        util.GetSpecificFilterParameters(eventnum, 1)
        return True
    except Exception:
        return False

# get the specific-filter count first
_, n_specific, _ = util.GetNumberEventFilters()
if not (0 <= eventnum < n_specific):
    raise KeyError(f'Events[{eventnum}] out of range; only {n_specific} specific filters')

Type guard

def event_filter_in_range(eventnum) -> bool:
    try:
        _, n_specific, _ = util.GetNumberEventFilters()
        return 0 <= eventnum < n_specific
    except Exception:
        return False

Try / catch

try:
    params = find_evt_by_number(eventnum)
except KeyError as e:
    if 'does not exist' in str(e):
        raise KeyError(f'stale event index {eventnum}; refresh from the Events container') from e
    raise

Prevention

When it happens

Trigger: Referencing a specific event filter index that does not exist (>= GetSpecificFilterParameters count); stale event index after the filter table changed; confusing specific-filter index with exception-filter index (see find_exc_by_number which uses a different offset).

Common situations: Hard-coded event filter index from a different target/debugger configuration; off-by-one between 0-based and 1-based numbering; index captured before new filters were added/removed.

Related errors

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