cocoindex-io/cocoindex · error · RuntimeError

change fingerprint {fp} is present in a cached memo entry bu

Error message

change fingerprint {fp} is present in a cached memo entry but has no registered state functions in the current ContextProvider — this should be unreachable under the shook-tag canonicalization invariant.

What it means

When replaying a cached memo entry, each stored change fingerprint must have state functions registered in the current ContextProvider. If a fingerprint is stored but unregistered, the shook-tag canonicalization invariant is broken — this is an internal consistency check and indicates a bug or stale/corrupted cache shared across environments.

Source

Thrown at python/cocoindex/_internal/function.py:417

    Used on cache-hit validation: for each stored ``fp → states`` entry we
    look up the matching state functions in the env registry.

    Under the shook-tag invariant this lookup always succeeds: if the user
    had removed ``__coco_memo_state__`` from the value's type between runs,
    the canonicalization would produce a different fingerprint (``hook`` vs
    ``shook`` tag) and the entry would already have been invalidated by
    `all_contained_with_env` before we reach this point. If a stored fp has
    no registered state fns we raise — that indicates registry/state drift
    or a bug in the shook-tag machinery.
    """
    if not stored:
        return []
    provider = env.context_provider
    entries: list[tuple[core.Fingerprint, list[StateFnEntry]]] = []
    for fp in stored:
        state_fns = provider.get_context_state_fns(fp)
        if state_fns is None:
            raise RuntimeError(
                f"change fingerprint {fp} is present in a cached memo "
                "entry but has no registered state functions in the current "
                "ContextProvider — this should be unreachable under the "
                "shook-tag canonicalization invariant."
            )
        entries.append((fp, state_fns))
    return entries


def _has_self_parameter(fn: Callable[..., Any]) -> bool:
    """Check if function has 'self' as first parameter (i.e., is a method)."""
    sig = inspect.signature(fn)
    params = list(sig.parameters.values())
    if not params:
        return False
    first = params[0]
    return first.name == "self" and first.kind in (
        inspect.Parameter.POSITIONAL_ONLY,

View on GitHub (pinned to e84aa99b32)

Solutions

1. Clear the memo cache / stored state for the affected function and re-run
2. Ensure the same functions are registered (same order) in the Environment providing the context state
3. Verify you're not mixing memo entries across different environments or processes
4. Report as a bug if reproducible with a single environment — it violates the documented invariant

provider = env.context_provider
missing = [fp for fp in cached_fingerprints if provider.get_context_state_fns(fp) is None]
if missing:
    clear_memo_cache()  # stale cache across environments

try:
    result = await memoized_fn(*args)
except RuntimeError as e:
    if "shook-tag canonicalization" in str(e):
        clear_memo_cache()
        result = await memoized_fn(*args)

When it happens

Trigger: Calling a memoized @coco.fn whose cached entry (from a previous run/environment) references fingerprints the current Environment's ContextProvider doesn't know — e.g. cache persisted across process restarts with a differently-populated provider, or functions registered in one environment but replayed in another.

Common situations: Sharing memo/LMDB storage between environments or processes; reordering context provider registrations; upgrading code where state functions were renamed/removed while old cache entries remain.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• coco.use_state() cannot be called inside a memoized function
• Memo state function returned an awaitable from a sync contex
• memo_key transform for *args must return tuple, got {type(va
• memo_key transform for **kwargs must return dict, got {type(
• Unknown memo_key parameter(s) for {qualified_name(fn)}(): {'

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/4da1bb07d3b7fc93. Report an issue: GitHub.