apache/druid · warning

Unable to queue cache operation

Error message

Unable to queue cache operation

What it means

MemcachedCache.get failed to enqueue an async GET with the Memcached client because the client's operation queue was full (IllegalStateException from asyncGet). The cache treats this as a miss: it increments errorCount and returns null instead of throwing. This is a cache-capacity/pressure signal, not a data error.

Solutions

1. Check memcached server health, memory, and network latency
2. Increase the cache timeout (timeoutSeconds) in the memcached cache config
3. Tune memcached client queue size / connection pool settings
4. Scale memcached or shard keys to reduce per-server load

Example fix

// before
druid.cache.type=memcached; druid.cache.timeout=100
// after: give the client more time and capacity
druid.cache.timeout=60000; verify memcached host reachability and increase client queue size

null

null

// Cache.get returns null on queue failure; treat null as a miss and fall back to the data source
byte[] val = cache.get(key); if (val == null) { /* fetch from segment storage */ }

When it happens

Trigger: asyncGet throws IllegalStateException because the client's outbound queue is full — operations cannot be queued before the queue timeout, typically under very high cache read rates or a slow/unresponsive memcached server.

Common situations: Memcached server saturated or unreachable, timeoutSeconds for the cache too low, read QPS exceeding the client queue capacity, connection pool exhausted.

Related errors

• Exception pulling item from cache
• Expected 0 resource count, got
• Invalid value provided for `druid.cache.clientMode`. Value…
• Unhandled locator type:
• cannot add element of size

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/c4dd6648a547b8e3. Report an issue: GitHub.

Appendix: source

Thrown at server/src/main/java/org/apache/druid/client/cache/MemcachedCache.java:490

        0,
        0,
        timeoutCount.get(),
        errorCount.get()
    );
  }

  @Override
  public byte[] get(NamedKey key)
  {
    try (ResourceHolder<MemcachedClientIF> clientHolder = client.get()) {
      Future<Object> future;
      try {
        future = clientHolder.get().asyncGet(computeKeyHash(memcachedPrefix, key));
      }
      catch (IllegalStateException e) {
        // operation did not get queued in time (queue is full)
        errorCount.incrementAndGet();
        log.warn(e, "Unable to queue cache operation");
        return null;
      }
      try {
        byte[] bytes = (byte[]) future.get(timeout, TimeUnit.MILLISECONDS);
        if (bytes != null) {
          hitCount.incrementAndGet();
        } else {
          missCount.incrementAndGet();
        }
        return bytes == null ? null : deserializeValue(key, bytes);
      }
      catch (TimeoutException e) {
        timeoutCount.incrementAndGet();
        future.cancel(false);
        return null;
      }
      catch (InterruptedException e) {
        Thread.currentThread().interrupt();

View on GitHub (pinned to 9b90983fd2)