uWSGI cache subsystem: hit ratio drops and 'full' insert failures

Response times are creeping upward on cached endpoints. Application logs show nothing. Worker busy ratio is normal. The cause is likely silent: uWSGI cache misses are increasing, and each miss forces the worker to compute or fetch the response instead of serving from shared memory.

This article covers uWSGI’s built-in cache subsystem (cache2), not external caches. If caches[] is absent from the stats server output, the uWSGI cache is not enabled and these diagnostics do not apply.

The stats server exposes cache metrics in the caches[] array. Two symptoms dominate: a rising miss rate with steady traffic (cache churn or insufficient capacity), and a non-zero full counter (insert operations failing because the cache has no free slots). Both degrade response time, but they have different root causes and fixes.

What it means

The uWSGI cache is an in-process key-value store backed by shared memory mapped across all workers. It is configured via cache2 in your uWSGI config. Each cache has a fixed number of slots (items) and a fixed block size (blocksize). When the cache is full, new insert attempts fail silently or with a warning, depending on configuration.

Three counters tell you almost everything:

The hit ratio is hits / (hits + miss). A drop with stable traffic means the cache is too small for the working set, or items are expiring before re-request.

The full counter is the more direct signal. Any non-zero value means the cache rejected an insert. Each rejected insert is a future cache miss for that key.

flowchart TD
    A[Cache miss rate rising] --> B{full counter greater than 0?}
    B -->|Yes| C[Cache capacity exhausted]
    B -->|No| D{items near max_items?}
    D -->|Yes| E[Undersized cache or churn]
    D -->|No| F{blocksize too small?}
    F -->|Possibly| G[Silent insert failures]
    F -->|No| H[TTL expiry too aggressive]
    C --> I[Increase items or enable purge_lru]
    E --> I
    G --> J[Increase blocksize]
    H --> K[Review expires values]

Common causes

Quick checks

# Dump all cache stats from the stats server
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.caches[]'

# Focused view of key cache metrics
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.caches[] | {name, items, max_items, hits, miss, full}'

# Calculate current hit ratio
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.caches[] | .hits as $h | .miss as $m | {name, hit_ratio: ($h / ($h + $m))}'

# Check whether items is near capacity
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.caches[] | {name, items, max_items, utilization: (.items / .max_items)}'

# Look for the DANGER full-cache warning in uWSGI logs
journalctl -u uwsgi --no-pager | grep "DANGER.*cache.*FULL"

# Check uWSGI version for known cache bugs
uwsgi --version

# Verify master process is running (required for cache sweeper)
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.pid'

Adjust the stats socket address (127.0.0.1:9191) to match your deployment. For UNIX socket stats, use uwsgi --connect-and-read /path/to/stats.sock.

How to diagnose it

1. Confirm the cache is enabled. Check your uWSGI config for cache2 directives. If the application uses Redis or Memcached internally, the uWSGI cache metrics are irrelevant. Verify by checking whether caches[] appears in the stats output.

2. Check the full counter trend. Take two readings a few minutes apart. If full is increasing, inserts are actively failing. If it is zero, the cache has room but misses are still rising (pointing to TTL or churn).

3. Check items versus max_items. If items is at or near max_items, the cache is full. The first slot of a cache is reserved internally, so a cache configured with items=1000 holds only 999; items at 999 with max_items of 1000 means the cache is at capacity.

4. Check hit ratio over time. If hit ratio is high immediately after a restart but degrades over hours, TTL expiry or eviction is too aggressive relative to the access pattern. If hit ratio is low from the start, the cache is undersized or the working set does not fit.

5. Check for silent insert failures. If items stays near zero despite the application attempting inserts, blocksize may be too small for the values being stored. A single-block cache stores at most blocksize - 1 bytes per item. Compare your actual response body sizes against the configured blocksize.

6. Check whether the master process is running. The cache sweeper thread, responsible for TTL-based expiration, only runs when the master process is enabled. Without it, expired items are never cleaned up and the cache fills permanently with stale entries. Confirm master = true in your config.

7. Check the uWSGI version if using purge_lru. purge_lru was added in 2.0.4; 2.0.7 fixed an off-by-one corruption bug in cache LRU mode and 2.0.24 fixed purge_lru cache initialization. If purge_lru=1 is set but eviction does not seem to work, upgrade to 2.0.24 or newer.

Metrics and signals to monitor

Fixes

Cache is undersized

Increase the items value in your cache2 configuration. Each item consumes blocksize bytes of shared memory, so the total footprint is items * blocksize. Verify the host has enough RAM for the larger allocation.

If you cannot increase items due to memory constraints, enable LRU eviction with purge_lru=1 (available since uWSGI 2.0.4). This evicts the least recently accessed item when the cache is full, making room for new inserts.

When purge_lru=1 is active, the expires argument on cache_set calls is ignored and eviction is purely access-based (official uWSGI docs). If you need TTL-based expiry alongside LRU eviction, do not rely on purge_lru; size the cache to hold the full working set instead.

Blocksize is too small

Increase blocksize to accommodate your largest cached value. For example, with blocksize=65536, the largest storable item is at most 65535 bytes. If your cached responses are larger, inserts fail silently with no error.

If values vary widely in size and most are small, consider bitmap mode (bitmap=1), which lets an item span multiple contiguous blocks and is production-ready since uWSGI 2.0.2. If you combine bitmap=1 with purge_lru=1, use uWSGI 2.0.24 or newer: 2.0.7 fixed an off-by-one corruption bug in cache LRU mode and 2.0.24 fixed purge_lru cache initialization.

TTL expiry too aggressive

Review the expires values passed to cache_set or configured in routing rules. If items expire before the next request for the same key, the cache provides no benefit. Increase expires to match or exceed the typical inter-request interval for each cached resource.

If you are using purge_lru=1, TTL expiry is not honored (see the caveat above). If TTL-based expiry is required, do not use purge_lru; size the cache to hold the full working set instead.

Master process not running

Enable master = true in your uWSGI config. Without the master process, the cache sweeper thread never starts, and TTL-based expiration does not work. Expired items accumulate until the cache is full of stale data with no mechanism to reclaim slots.

Suppressing full-cache log warnings

If you have consciously decided to let the cache run full (for example, with purge_lru handling eviction), the repeated *** DANGER cache "<name>" is FULL !!! *** log lines on every insert can flood your logs. Use ignore_full (added in uWSGI 2.0.4) to suppress these warnings only when you have an eviction strategy in place. Otherwise it hides a real capacity problem.

Prevention

• Size the cache to the working set, not to a round number. Measure how many unique keys the application references within the TTL window. Set items to at least 120% of that count to allow for growth.
• Match blocksize to actual value sizes. Audit your largest cached responses and set blocksize with headroom. Silent insert failures from blocksize mismatch are the hardest to diagnose because they produce no error.
• Monitor the full counter as a rate, not as an absolute. Any non-zero rate means inserts are being rejected. Alert on it.
• Track hit ratio over time, not just point-in-time. A slowly declining hit ratio over days or weeks indicates the working set is growing past cache capacity.
• Verify the master process is enabled if you rely on TTL expiry. Without the sweeper thread, the cache fills with expired entries and never recovers.
• Keep uWSGI current. The cache subsystem has received fixes in recent 2.0.x releases. Verify which bugs affect your version before relying on purge_lru or bitmap mode.

How Netdata helps

Netdata collects uWSGI cache metrics from the stats server at per-second resolution. Correlate these signals during investigation:

• Cache hit and miss rates over time. Reveals whether a declining hit ratio is gradual (working set growth) or sudden (code change or traffic shift).
• The full counter rate. The most direct signal of capacity exhaustion. Per-second collection catches burst insert failures that coarser polling intervals miss.
• Miss rate vs. worker avg_rt. Confirms cache misses are the cause of response time degradation, not a downstream dependency.
• items relative to max_items. Shows proximity to capacity before inserts start failing.
• Anomaly detection on hit ratio. Surfaces slow working-set drift over weeks that static thresholds would miss.

Related guides

• uWSGI all workers busy: reading the busy ratio before the queue fills
• uWSGI avg_rt is not a real average: why the latency number lies
• uWSGI chain reload: cycling workers one at a time for zero-downtime deploys
• uWSGI cheaper subsystem: dynamic worker scaling and the false ‘missing workers’ alert
• uWSGI connection refused: clients turned away when the backlog overflows
• uWSGI file descriptor limits: raising ulimit -n and systemd LimitNOFILE
• uWSGI in gevent/async mode: why worker busy ratio stops meaning anything
• uWSGI threaded mode and the GIL: why more threads don’t add CPU parallelism
• uWSGI reload thundering herd: capacity drops to zero during a slow restart
• uWSGI harakiri death spiral: workers killed and respawned while throughput collapses
• uWSGI harakiri not configured: stuck workers with no timeout and no recovery
• uWSGI harakiri timeout: setting it against request duration and nginx timeouts