{"record":{"id":"3c8344924cebeba1","repo":"huggingface/transformers","slug":"you-should-provide-exactly-one-of-layers-or-lay","errorCode":null,"errorMessage":"You should provide exactly one of `layers` or `layer_class_to_replicate` to initialize a Cache.","messagePattern":"You should provide exactly one of `layers` or `layer_class_to_replicate` to initialize a Cache\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/cache_utils.py","lineNumber":1296,"sourceCode":"            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\n    def __len__(self):\n        \"\"\"\n        This value corresponds to the number of layers in the model.\n        \"\"\"\n        # Note: for DynamicCache, layers are initialized lazily, so this will not be accurate before the first\n        # forward through all the layers","sourceCodeStart":1278,"sourceCodeEnd":1314,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cache_utils.py#L1278-L1314","documentation":"Cache.__init__ raises ValueError when neither layers nor layer_class_to_replicate is given. The constructor requires exactly one of the two so the cache knows whether it holds pre-built layers or grows layers lazily on update().","triggerScenarios":"Calling Cache() or a subclass whose __init__ forwards no layer arguments — e.g. a custom subclass that forgets to pass layer_class_to_replicate up to super().__init__.","commonSituations":"Writing a custom Cache subclass and overriding/chaining __init__ incorrectly; upgrading transformers versions where constructor signatures of DynamicCache/Cache changed and old call sites no longer supply the needed argument.","solutions":["For a lazily-growing cache pass layer_class_to_replicate (as DynamicCache does): Cache(layer_class_to_replicate=DynamicCacheLayer)","For a fixed-layout cache pass the full layers list","If subclassing, ensure your __init__ forwards one of the two to super().__init__"],"exampleFix":"# before\nclass MyCache(Cache):\n    def __init__(self):\n        super().__init__()  # ValueError\n\n# after\nclass MyCache(Cache):\n    def __init__(self):\n        super().__init__(layer_class_to_replicate=DynamicCacheLayer)","handlingStrategy":"validation","validationCode":"def make_cache(layers=None, layer_class=None):\n    if layers is None and layer_class is None:\n        layer_class = DynamicCacheLayer\n    return Cache(layers=layers, layer_class_to_replicate=layer_class)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default layer_class_to_replicate in custom Cache subclasses so callers never construct empty","Prefer using DynamicCache() directly for the lazy case instead of the Cache base class"],"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"}