{"record":{"id":"5d25db6733dc8193","repo":"huggingface/transformers","slug":"you-can-construct-a-cache-either-from-a-list-laye","errorCode":null,"errorMessage":"You can construct a Cache either from a list `layers` of all the predefined `CacheLayer`, or from a `layer_class_to_replicate`, in which case the Cache will append a new layer corresponding to `layer_class_to_replicate` for each new call to `update` with an idx not already in the Cache.","messagePattern":"You can construct a Cache either from a list `layers` of all the predefined `CacheLayer`, or from a `layer_class_to_replicate`, in which case the Cache will append a new layer corresponding to `layer_class_to_replicate` for each new call to `update` with an idx not already in the Cache\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/cache_utils.py","lineNumber":1290,"sourceCode":"            Only used if `layers` is omitted (`None`), in which case it will be used as the base class for each layer,\n            and the layers will be added lazily as soon as `update` is called with a `layer_idx` greater than the current\n            list of layers.\n        offloading (`bool`, *optional*, defaults to `False`):\n            Whether to perform offloading of the layers to `cpu`, to save GPU memory.\n        offload_only_non_sliding (`bool`, *optional*, defaults to `True`):\n            If `offloading` is `True`, this further decides if only the non-sliding layers will be offloaded (because\n            usually the sliding layers are small in size, so there is no need to offload them, and skipping it is faster).\n    \"\"\"\n\n    def __init__(\n        self,\n        layers: list[CacheLayerMixin | LinearAttentionCacheLayerMixin] | None = None,\n        layer_class_to_replicate: type[CacheLayerMixin | LinearAttentionCacheLayerMixin] | None = None,\n        offloading: bool = False,\n        offload_only_non_sliding: bool = True,\n    ):\n        if layers is not None and layer_class_to_replicate is not None:\n            raise ValueError(\n                \"You can construct a Cache either from a list `layers` of all the predefined `CacheLayer`, or from a \"\n                \"`layer_class_to_replicate`, in which case the Cache will append a new layer corresponding to \"\n                \"`layer_class_to_replicate` for each new call to `update` with an idx not already in the Cache.\"\n            )\n        if layers is None and layer_class_to_replicate is None:\n            raise ValueError(\n                \"You should provide exactly one of `layers` or `layer_class_to_replicate` to initialize a Cache.\"\n            )\n        self.layers = layers if layers is not None else []\n        self.layer_class_to_replicate = layer_class_to_replicate\n        self.offloading = offloading\n        if self.offloading:\n            self.only_non_sliding = offload_only_non_sliding\n            self.prefetch_stream = torch.Stream() if _is_torch_greater_or_equal_than_2_7 else torch.cuda.Stream()\n\n    def __repr__(self):\n        return f\"{self.__class__.__name__}(layers={self.layers})\"\n","sourceCodeStart":1272,"sourceCodeEnd":1308,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cache_utils.py#L1272-L1308","documentation":"Cache.__init__ raises ValueError when both layers and layer_class_to_replicate are provided. The Cache base class supports two mutually exclusive construction modes: pre-built layers (static caches like StaticCache/QuantizedCache) or lazy replication of a class per layer (DynamicCache), never both.","triggerScenarios":"Calling Cache(layers=[...], layer_class_to_replicate=DynamicCacheLayer) or a subclass whose __init__ forwards both arguments, e.g. DynamicCache(layers=my_layers, layer_class_to_replicate=...).","commonSituations":"Subclassing Cache or DynamicCache and passing through a user-supplied layer list while a default layer_class_to_replicate is also set; migrating code from older transformers where DynamicCache() took no arguments and then adding preloaded layers (e.g. from from_legacy_cache-style data).","solutions":["Pass exactly one: either layers=[CacheLayer...] (pre-initialized, e.g. for static/quantized caches) or layer_class_to_replicate=SomeLayerClass (lazy, e.g. DynamicCache)","If you want a DynamicCache pre-filled with tensors, pass layers built from your tensors instead of layer_class_to_replicate","Check subclass __init__ defaults that may silently fill in one of the two arguments"],"exampleFix":"# before\ncache = DynamicCache(layers=prefilled_layers, layer_class_to_replicate=DynamicCacheLayer)\n\n# after\ncache = DynamicCache(layers=prefilled_layers)","handlingStrategy":"validation","validationCode":"assert not (layers is not None and layer_class_to_replicate is not None), (\n    \"pass exactly one of layers / layer_class_to_replicate\"\n)\ncache = Cache(layers=layers) if layers is not None else Cache(layer_class_to_replicate=DynamicCacheLayer)","typeGuard":null,"tryCatchPattern":"try:\n    cache = Cache(layers=layers, layer_class_to_replicate=cls)\nexcept ValueError:\n    cache = Cache(layers=layers)  # prefer pre-built layers when both were supplied","preventionTips":["In subclasses, make layer_class_to_replicate a fixed class attribute instead of an __init__ parameter","Pass pre-built layers for static layouts and the replicate class for dynamic ones — never mix"],"tags":["cache","constructor","validation","valueerror"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}