apache/druid · error · IllegalStateException

got an exception while loading key

Error message

got an exception while loading key [%s]

What it means

OffHeapLoadingCache.get() invokes the user-configured valueLoader to populate the off-heap cache; if the loader throws any Exception, it is wrapped in an ISE with the offending key. The root cause is always in the underlying data feed the lookup loads from.

Solutions

1. Inspect the wrapped cause exception to find the actual load failure (network, parse, IO)
2. Verify the lookup data source URL/file is reachable and returns valid data for the key
3. Retry once the data source is healthy; consider caching/health-checking the feed

Example fix

// before
value = valueLoader.call();
// after
try {
  value = valueLoader.call();
} catch (IOException e) {
  log.warn("retrying lookup load for key %s", key);
  value = valueLoader.call();
}

// before get(): check feed health
// new URL(lookupUri).openConnection().connect(); // fails fast if unreachable

try { return cache.get(key); } catch (ISE e) { log.error("lookup load failed for key {} cause {}", key, e.getCause()); throw e.getCause() instanceof IOException ? new RetryableException(e.getCause()) : e; }

When it happens

Trigger: A lookup's valueLoader (e.g. a map population from a URI/URL feed) throws while loading a specific key during cache population on first get().

Common situations: The lookup's data source (HTTP endpoint or file) is temporarily down or returns malformed data; network timeouts during first access after startup; permissions issues reading the feed.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Already shut down, not starting again
• Already started, not starting again
• Cache reference is null
• can't start.
• can't stop.

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

Appendix: source

Thrown at extensions-core/lookups-cached-single/src/main/java/org/apache/druid/server/lookup/cache/loading/OffHeapLoadingCache.java:147

    }
    return builder.build();
  }

  @Override
  public V get(K key, final Callable<? extends V> valueLoader)
  {
    synchronized (key) {
      V value = cache.get(key);
      if (value != null) {
        return value;
      }
      try {
        value = valueLoader.call();
        cache.put(key, value);
        return value;
      }
      catch (Exception e) {
        throw new ISE(e, "got an exception while loading key [%s]", key);
      }
    }
  }


  @Override
  public void putAll(Map<? extends K, ? extends V> m)
  {
    cache.putAll(m);
  }

  @Override
  public void invalidate(K key)
  {
    cache.remove(key);
  }

  @Override

View on GitHub (pinned to 9b90983fd2)