{"record":{"id":"4ed97f5bce6ecbb3","repo":"huggingface/transformers","slug":"cannot-call-update-indexer-on-layer-layer-idx","errorCode":null,"errorMessage":"Cannot call `update_indexer` on layer {layer_idx} which is a {type(self.layers[layer_idx]).__name__}; it has no indexer key cache (expected a `DynamicIndexedLayer` or `StaticIndexedLayer`).","messagePattern":"Cannot call `update_indexer` on layer (.+?) which is a (.+?); it has no indexer key cache \\(expected a `DynamicIndexedLayer` or `StaticIndexedLayer`\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/cache_utils.py","lineNumber":1441,"sourceCode":"            raise ValueError(\"Cannot call `update_conv_state` on a non-LinearAttention layer!\")\n        recurrent_states = self.layers[layer_idx].update_recurrent_state(recurrent_states, state_idx, **kwargs)\n        return recurrent_states\n\n    def update_indexer(self, indexer_key_states: torch.Tensor, layer_idx: int) -> torch.Tensor:\n        \"\"\"\n        Updates the indexer key cache for layer `layer_idx`.\n\n        Parameters:\n            indexer_key_states (`torch.Tensor`):\n                The new indexer key states to cache, shape `[batch_size, seq_len, index_head_dim]`.\n            layer_idx (`int`):\n                The index of the layer to cache the states for.\n\n        Return:\n            `torch.Tensor`: The updated indexer key states (full cache).\n        \"\"\"\n        if not hasattr(self.layers[layer_idx], \"update_indexer\"):\n            raise ValueError(\n                f\"Cannot call `update_indexer` on layer {layer_idx} which is a \"\n                f\"{type(self.layers[layer_idx]).__name__}; it has no indexer key cache \"\n                f\"(expected a `DynamicIndexedLayer` or `StaticIndexedLayer`).\"\n            )\n        return self.layers[layer_idx].update_indexer(indexer_key_states)\n\n    def early_initialization(\n        self,\n        batch_size: int,\n        num_heads: int | list[int],\n        head_dim: int | list[int],\n        dtype: torch.dtype,\n        device: torch.device,\n    ):\n        \"\"\"\n        Initialize all the layers in advance (it's otherwise lazily initialized on the first `update` call).\n        This is useful for our `export` recipes, as `export` needs everything in advance.\n        \"\"\"","sourceCodeStart":1423,"sourceCodeEnd":1459,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cache_utils.py#L1423-L1459","documentation":"Cache.update_indexer() raises ValueError when the target layer has no update_indexer attribute, i.e. it is not an indexed layer (DynamicIndexedLayer / StaticIndexedLayer as used by indexer-based architectures like Kimi K2 / MoonViT-style retrieval attention). The check is duck-typed via hasattr.","triggerScenarios":"Calling cache.update_indexer(indexer_key_states, layer_idx=i) where layers[i] is a plain attention or linear attention layer without an indexer key cache.","commonSituations":"Reusing indexer-cache code from a retrieval-augmented model on a model without indexer support; wrong layer_idx mapping after model surgery or layer pruning.","solutions":["Only call update_indexer on layers that are DynamicIndexedLayer or StaticIndexedLayer","Guard with hasattr(cache.layers[layer_idx], 'update_indexer') before calling","Verify the model config actually declares indexer heads before driving the indexer cache manually"],"exampleFix":"# before\ncache.update_indexer(key_states, layer_idx=idx)\n\n# after\nif hasattr(cache.layers[idx], \"update_indexer\"):\n    cache.update_indexer(key_states, layer_idx=idx)","handlingStrategy":"type-guard","validationCode":"if hasattr(cache.layers[layer_idx], \"update_indexer\"):\n    cache.update_indexer(indexer_key_states, layer_idx=layer_idx)","typeGuard":"def has_indexer_cache(layer) -> bool:\n    return hasattr(layer, \"update_indexer\") and callable(layer.update_indexer)","tryCatchPattern":null,"preventionTips":["Gate indexer cache code on model capability (e.g. config.index_head_dim or model type), not on generic layer indices","Centralize 'which layers support which cache APIs' checks next to the cache construction"],"tags":["cache","indexer","layer-type","valueerror"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}