{"record":{"id":"c8b50ce6020d4d55","repo":"huggingface/transformers","slug":"num-head-was-provided-as-a-list-of-length-len-n","errorCode":null,"errorMessage":"`num_head` was provided as a list of length {len(num_heads)}, but the Cache currently has {len(self.layers)} layers","messagePattern":"`num_head` was provided as a list of length (.+?), but the Cache currently has (.+?) layers","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/cache_utils.py","lineNumber":1467,"sourceCode":"        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        \"\"\"\n        # To allow different num_heads and head_dim depending on layers, we accept lists\n        if isinstance(num_heads, int):\n            num_heads = [num_heads] * len(self)\n        if isinstance(head_dim, int):\n            head_dim = [head_dim] * len(self)\n\n        if len(num_heads) != len(self.layers):\n            raise ValueError(\n                f\"`num_head` was provided as a list of length {len(num_heads)}, but the Cache currently has {len(self.layers)} layers\"\n            )\n        if len(head_dim) != len(self.layers):\n            raise ValueError(\n                f\"`head_dim` was provided as a list of length {len(num_heads)}, but the Cache currently has {len(self.layers)} layers\"\n            )\n\n        for layer, layer_num_heads, layer_head_dim in zip(self.layers, num_heads, head_dim):\n            if not layer.supports_early_init or layer.is_initialized:\n                continue\n            # Note that the initialization needs all dimensions (except -2), as well as device and dtype, so we use\n            # this fake tensor approach. It has size 0 on the -2 dimension, so it does not allocate any data (it only\n            # creates an empty tensor with correct shape, dtype and device), which is very efficient and practical\n            fake_kv_tensor = torch.zeros((batch_size, layer_num_heads, 0, layer_head_dim), dtype=dtype, device=device)\n            # Init the layer\n            layer.lazy_initialization(fake_kv_tensor, fake_kv_tensor)\n\n    def get_seq_length(self, layer_idx: int = 0) -> int:","sourceCodeStart":1449,"sourceCodeEnd":1485,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cache_utils.py#L1449-L1485","documentation":"Cache.early_initialization() raises ValueError when num_heads is given as a list whose length differs from the number of layers in the cache. Per-layer head counts must align one-to-one with cache layers; ints are broadcast to all layers, lists must match len(self.layers) exactly.","triggerScenarios":"Calling cache.early_initialization(batch_size, num_heads=[3, 8], ...) on a cache whose layer count (from config.num_hidden_layers or the layers list) is not 2. Typical in export flows that pre-initialize everything.","commonSituations":"Exporting a model with heterogeneous head counts where the num_heads list was built from a different config (text vs. vision sub-config); passing num_heads for one model with a cache built from another; off-by-one when slicing config lists.","solutions":["Make len(num_heads) equal the number of cache layers, or pass a single int to broadcast","Verify against config.get_text_config().num_hidden_layers when using layer_class_to_replicate caches","For nested configs, derive num_heads from the same config used to build the cache"],"exampleFix":"# before\ncache.early_initialization(bs, num_heads=[3, 8], head_dim=[128], ...)  # cache has 28 layers\n\n# after\ncache.early_initialization(bs, num_heads=3, head_dim=128, dtype=torch.bfloat16, device=device)","handlingStrategy":"validation","validationCode":"n_layers = len(cache.layers)\nif isinstance(num_heads, list):\n    assert len(num_heads) == n_layers, f\"num_heads list must have {n_layers} entries\"\ncache.early_initialization(batch_size, num_heads=num_heads, head_dim=head_dim, dtype=dtype, device=device)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass ints when all layers share num_heads — they broadcast automatically","Build num_heads/head_dim lists from the same config that sized the cache","This API exists mainly for export flows; runtime generate() rarely needs it"],"tags":["cache","early-initialization","export","shape-mismatch","valueerror"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}