huggingface/transformers · error · ValueError

Expected 1 or 2 arguments, got {len(caches)}

Error message

Expected 1 or 2 arguments, got {len(caches)}

What it means

EncoderDecoderCache.__init__ accepts either exactly one argument (a DDP-style iterable of per-layer cache data tuples) or exactly two arguments (a self-attention Cache and a cross-attention Cache). This ValueError is raised for any other argument count: zero or three-or-more positional arguments.

Source

Thrown at src/transformers/cache_utils.py:1997

                    self_attention_cache_data.append(combined_cache_data[:3])
                    cross_attention_cache_data.append(combined_cache_data[3:])
                # To support old DDP-style init, we handle the case where the tuple has no sliding window tensor
                elif len(combined_cache_data) == 4:  # two tuple of style (self_attn_k, self_attn_v)
                    self_attention_cache_data.append(combined_cache_data[:2])
                    cross_attention_cache_data.append(combined_cache_data[2:])
                else:
                    raise ValueError(f"Expected {len(combined_cache_data) = } to be 4 or 6.\n{combined_cache_data = }")
            self.self_attention_cache = DynamicCache(self_attention_cache_data)
            self.cross_attention_cache = DynamicCache(cross_attention_cache_data)
        # Otherwise, we should get two arguments, a self-attention cache and a cross-attention cache
        elif len(caches) == 2:
            if not isinstance(caches[0], Cache) or not isinstance(caches[1], Cache):
                raise TypeError(f"One of the two arguments is not a Cache: {type(caches[0]) = }, {type(caches[1]) = }")
            self.self_attention_cache = caches[0]
            self.cross_attention_cache = caches[1]
        # Error case
        else:
            raise ValueError(f"Expected 1 or 2 arguments, got {len(caches)}")

        self.is_updated = {}
        for layer_idx in range(len(self.cross_attention_cache)):
            self.is_updated[layer_idx] = bool(self.cross_attention_cache.get_seq_length(layer_idx) > 0)

    def __iter__(self):
        """Returns tuples of style (self_attn_k, self_attn_v, self_attn_sliding, cross_attn_k, cross_attn_v, cross_attn_sliding)"""
        for self_attention_layer, cross_attention_layer in zip(self.self_attention_cache, self.cross_attention_cache):
            yield self_attention_layer + cross_attention_layer

    def __repr__(self) -> str:
        return (
            f"{self.__class__.__name__}(self_attention_cache={self.self_attention_cache}, cross_attention_cache="
            f"{self.cross_attention_cache})"
        )

    def __len__(self):
        """

View on GitHub (pinned to a597f97485)

Solutions

  1. Pass exactly two Cache instances: EncoderDecoderCache(self_attention_cache, cross_attention_cache)
  2. Or pass exactly one iterable of per-layer tuples (each of length 4 or 6) for DDP-style init
  3. If splatting a list, check its length is 1 or 2 before the call

Example fix

// before
caches = [self_cache, cross_cache, extra]
enc_dec = EncoderDecoderCache(*caches)

// after
enc_dec = EncoderDecoderCache(caches[0], caches[1])
Defensive patterns

Strategy: validation

Validate before calling

assert 1 <= len(caches) <= 2, f"EncoderDecoderCache takes 1 or 2 args, got {len(caches)}"

Try / catch

try:
    enc = EncoderDecoderCache(*caches)
except ValueError as e:
    if "Expected 1 or 2 arguments" in str(e):
        raise ValueError(f"Bad cache list length {len(caches)}; check how caches were collected") from e
    raise

Prevention

When it happens

Trigger: Calling EncoderDecoderCache() with no args; passing three caches, e.g. EncoderDecoderCache(a, b, c); unpacking a list incorrectly such as EncoderDecoderCache(*three_items); or passing the same cache twice plus a third config object.

Common situations: Building the cache in a loop where the number of collected caches varies; refactoring from a 2-tuple to a 3-tuple of caches; splatting a list whose length is not 1 or 2.

Related errors

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