Troubleshooting

Redis-backed code does not compile

Check the feature flags first:

• local-only usage: no Redis feature
• Tokio runtime: redis-tokio
• Smol runtime: redis-smol

You must enable exactly one Redis runtime feature, never both.

Redis-backed methods fail at runtime

Verify:

• Redis 7.2+ is running
• REDIS_URL points to the right instance
• your application created a connection_manager

Limits look inconsistent across instances

That usually means one of these:

• you are using the local provider by mistake
• Redis-backed instances are not sharing the same namespace or options
• you are using hybrid and seeing expected sync lag

Keys fail validation

RedisKey must:

• not be empty
• be at most 255 bytes
• not contain :

Cleanup does not seem to run

Remember the construction rule:

• build() starts cleanup automatically
• new(...) requires run_cleanup_loop()

If you still see stale state, check whether the process actually stays alive long enough for the cleanup loop to run.