# Transformers 5.24 Renamed past_key_values: How to Migrate to cache

Update custom generation loops and cache adapters without passing both names, then check that the second decode step still reuses the cache.

By Paras Madan | 2026-11-22


[Hugging Face Transformers 5.24.0](https://github.com/huggingface/transformers/releases/tag/v5.24.0), released November 21, standardizes the generation cache name on `cache`. Attention models previously used `past_key_values`, while some state-space and linear-attention models used `cache_params`. The migration matters most if your code manages decoding itself, inspects a model's signature or wraps a custom cache.

Older calls still have a compatibility window. The easy mistake is sending the new keyword from your code while an older wrapper quietly forwards the old one. Transformers rejects that combination.

## Find the code that owns the cache

Search your project for both old names. Separate reads from writes: a custom decoding loop might read the previous response's cache, pass it into the next forward call and expose it through its own result object. Updating one of those paths leaves the others dependent on compatibility aliases.

Use `cache` for the argument you pass to a 5.24 model and for the field you read from its output. The [release notes](https://github.com/huggingface/transformers/releases/tag/v5.24.0#breaking-changes) say the old input names issue a deprecation warning. Their compatibility is planned until v5.40.0 for `forward` and `prepare_inputs_for_generation`, and until v6.0.0 for `generate`. Do not read the longer `generate` window as permission to keep the old name inside a custom model.

## Send only one spelling

If your app supports installations on both sides of 5.24, keep the compatibility decision at the model integration layer. In a dependency range you test, map the app's cache to the keyword the wrapped model expects. Avoid adding both keyword names to a request as a hedge. A wrapper that forwards both, even when they refer to the same cache, can trigger the documented `ValueError`.

Audit output handling too. The existing output aliases still work in 5.24, so a single generated response can look fine while a downstream serialization step still looks for an old field. If your own service exposes a stable result schema, adapt the internal model output without silently renaming a field your callers rely on.

## Check custom caches and PEFT separately

The [implementation discussion](https://github.com/huggingface/transformers/pull/50585) explains why the library's cache calls now pass a named `kwargs` argument to `update`. If you override that method, accept what the library now supplies and check that any needed data still reaches your implementation. A test with the built-in cache will not validate your subclass.

The release requires `peft>=0.22.0` when using PEFT. Include that dependency in the same upgrade check if you ship adapters. Testing the base checkpoint alone can miss problems in code that inspects the forward signature or wraps a tuned model.

## Test the second step, not just the first

For an owned test model, pick one short synthetic prompt and hold the checkpoint, inputs and decoding settings constant. Compare a simple deterministic generation against your existing baseline. Then exercise the actual path your application uses: run a prefill followed by another decode step with the returned cache passed back into the model. Compare the next token with an equivalent full-prefix run and check that your integration did not silently drop the cache.

Run that test with the adapters or cache subclasses you actually deploy. If your code uses an attention model and a hybrid model, test both. A clean first answer is a weak upgrade signal when the code you changed only runs on the second step.

I'm Paras. I help AI teams turn technical releases into practical guides developers can use.

[Book a 30-minute call](https://cal.com/paras-madan/30min).
