Guides

Troubleshooting

Common v2 setup and runtime issues across local, Redis, and hybrid providers.

Live key cards remain active while faded stale cards are selected by a periodic cleanup sweep. — Lazy expiry keeps reads current; the optional background loop removes inactive state over time.

Redis-backed code does not compile

Enable exactly one runtime feature: redis-tokio or redis-smol. Local provider needs neither.

Redis operations fail

Verify Redis 7.2+, connection URL, connection manager, and consistent prefixes.

v2 removed RateLimiter, RateLimiterOptions, provider option structs, and numeric configuration setters. Construct LocalRateLimiterProvider, RedisRateLimiterProvider, or HybridRateLimiterProvider directly and use semantic configuration types. See Configuration Types for the v2 replacements and defaults.

Limits differ across instances

Local state is process-scoped.
Redis-backed instances must share namespace and settings.
Hybrid decisions may lag remote state until synchronization.

Redis keys fail validation

RedisKey must be non-empty, at most 255 bytes, and contain no :.

Cleanup does not run

build() starts cleanup unless builder disabled it. Call start_cleanup_loop() after a manual stop; calls are idempotent. Hybrid synchronization is not stopped by disabling cleanup.

Cleanup

Configure and control stale-state cleanup for every provider.

API Reference Guide