huggingface/transformers · error · ValueError

You should provide exactly one of `layers` or `layer_class_t

Error message

You should provide exactly one of `layers` or `layer_class_to_replicate` to initialize a Cache.

What it means

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().

Source

Thrown at src/transformers/cache_utils.py:1296

            If `offloading` is `True`, this further decides if only the non-sliding layers will be offloaded (because
            usually the sliding layers are small in size, so there is no need to offload them, and skipping it is faster).
    """

    def __init__(
        self,
        layers: list[CacheLayerMixin | LinearAttentionCacheLayerMixin] | None = None,
        layer_class_to_replicate: type[CacheLayerMixin | LinearAttentionCacheLayerMixin] | None = None,
        offloading: bool = False,
        offload_only_non_sliding: bool = True,
    ):
        if layers is not None and layer_class_to_replicate is not None:
            raise ValueError(
                "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."
            )
        if layers is None and layer_class_to_replicate is None:
            raise ValueError(
                "You should provide exactly one of `layers` or `layer_class_to_replicate` to initialize a Cache."
            )
        self.layers = layers if layers is not None else []
        self.layer_class_to_replicate = layer_class_to_replicate
        self.offloading = offloading
        if self.offloading:
            self.only_non_sliding = offload_only_non_sliding
            self.prefetch_stream = torch.Stream() if _is_torch_greater_or_equal_than_2_7 else torch.cuda.Stream()

    def __repr__(self):
        return f"{self.__class__.__name__}(layers={self.layers})"

    def __len__(self):
        """
        This value corresponds to the number of layers in the model.
        """
        # Note: for DynamicCache, layers are initialized lazily, so this will not be accurate before the first
        # forward through all the layers

View on GitHub (pinned to a597f97485)

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__

Example fix

# before
class MyCache(Cache):
    def __init__(self):
        super().__init__()  # ValueError

# after
class MyCache(Cache):
    def __init__(self):
        super().__init__(layer_class_to_replicate=DynamicCacheLayer)

Defensive patterns

Strategy: validation

Validate before calling

def make_cache(layers=None, layer_class=None):
    if layers is None and layer_class is None:
        layer_class = DynamicCacheLayer
    return Cache(layers=layers, layer_class_to_replicate=layer_class)

Prevention

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

When it happens

Trigger: 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__.

Common situations: 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.

Related errors

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/3c8344924cebeba1. Report an issue: GitHub.