RedisCacheWriter default changed from synchronous to asynchronous in 4.x without clear migration notice

[hyeongguen-song]

Summary

In Spring Data Redis 4.x, RedisCacheWriter.put() now defaults to
asynchronous (fire-and-forget) writes when a ReactiveRedisConnectionFactory
(e.g., Lettuce) is present. This is a silent behavioral change from 3.x where
writes were always synchronous/blocking.

There is no mention of this change in the migration guide, making it very
difficult to diagnose cache inconsistencies after upgrading.

Environment

• Spring Data Redis: 3.x → 4.x
• Redis driver: Lettuce (ReactiveRedisConnectionFactory)

Problem

What changed internally

In DefaultRedisCacheWriter, the constructor now accepts an asynchronousWrites
flag, which defaults to true when a ReactiveRedisConnectionFactory is
detected:

// DefaultRedisCacheWriter.java (4.x)
if (REACTIVE_REDIS_CONNECTION_FACTORY_PRESENT
        && connectionFactory instanceof ReactiveRedisConnectionFactory) {
    this.asyncCacheWriter = new AsynchronousCacheWriterDelegate();
    this.asynchronousWrites = asynchronousWrites; // defaults to true via nonLockingRedisCacheWriter
}

// put() in 4.x — fire-and-forget when asynchronousWrites = true
if (writeAsynchronously()) {
    asyncCacheWriter.store(name, key, value, ttl)
        .thenRun(() -> statistics.incPuts(name)); // no error handling
} else {
    execute(name, connection -> { doPut(...); return "OK"; });
}

In 3.x, put() was always a blocking call. There was no async path.

Real-world impact: cache warmup in batch applications

A common pattern is running a short-lived batch application to pre-warm the
cache before the main application starts:

Batch app starts
  → calls @Cacheable method
  → transaction commits
  → afterCommit() fires → cacheWriter.put()
  → async write is scheduled (fire-and-forget)
Batch app finishes → Spring context closes → Lettuce Netty event loop shuts down
  → in-flight async write is dropped
  → cache entry never reaches Redis
Main app starts → cache miss on every request

This behavior is non-deterministic: if the async write happens to complete
before the context closes, the cache is populated. Otherwise, it silently fails.
No exception is thrown. No log is emitted.

After upgrading from 3.x to 4.x, our cache warmup batch stopped working
intermittently — with no error in sight.

Workaround

The immediateWrites() option on RedisCacheWriterConfigurer restores
synchronous write behavior:

RedisCacheWriter writer = RedisCacheWriter.create(connectionFactory,
    config -> config.immediateWrites());

RedisCacheManager manager = RedisCacheManagerBuilder
    .fromCacheWriter(writer)
    .build();

This works, but:

1. It is not mentioned in the migration guide from 3.x to 4.x
2. The API surface of RedisCacheWriterConfigurer is not easy to discover
3. Users migrating from 3.x have no reason to look for this option

Suggestion

1. Add a note to the migration guide explaining that writes are now
   asynchronous by default when using a reactive driver, and document
   immediateWrites() as the opt-in for the previous behavior.
2. Log a warning when an async write fails (instead of silently dropping it).

[lukaszungier]

Great catch.
I wanted to add some context regarding that non-explicit change we've observed.

In one of our projects, we test the caching layer by invoking a cached method twice in immediate succession to verify the underlying logic only executes once. Since migrating to Spring Boot 4, these tests have become non-deterministic, failing intermittently (between 0% and 10% of the time).

This is exactly the same reason.

[mp911de]

Thank you for your issue report. We appreciate community contributions, but we do need them to meet a reasonable baseline for consideration.

Tip

This means:

• Expressing your intent with a concise and reasonable description
• Providing what situation you've encountered, describing your setup, ideally with a reproducer
  provided as GitHub repository, and what you would expect

When issues require significant effort from our side to initially understand your request, we have to deprioritize or even reject them in favor of tickets that are ready for discussion as we have to be mindful of our limited time, and we need to focus it where it has the most impact. If you would like us to spend some time working on this issue, please spend some time making this a substantial and quality ticket description.

When describing your concern, please focus on the aspects that matter. There's no need to duplicate parts of our code in the description or use excessive summarization or bullet lists. Instead, use rather links if you want to point out subtle details that matter in the specific context. Avoid conflicting requests such as asking for guidance and then answering questions yourself, as such descriptions neglect raising a ticket in the first place.

Important

Help us understand:

• Your reasoning for the approach you've chosen
• Trade-offs you considered
• Any areas where you're uncertain and would value guidance

Concise, thoughtful explanations of your decision-making process are far more valuable than detailed restatements of the code.

There is no mention of this change in the migration guide, making it very
difficult to diagnose cache inconsistencies after upgrading.

The bugfix change has been made in a major revision effort through #3236 and a migration is outlined in our release notes at https://github.com/spring-projects/spring-data-commons/wiki/Spring-Data-2025.1-Release-Notes#cache-contract-refinements-in-rediscache.

Please let us know (without a wall of text using recursive summarization) whether you are missing something and how we can improve.

[spring-projects-issues]

If you would like us to look at this issue, please provide the requested information. If the information is not provided within the next 7 days this issue will be closed.

[spring-projects-issues]

Closing due to lack of requested feedback. If you would like us to look at this issue, please provide the requested information and we will re-open the issue.