apache/druid · error · QueryException (RE)

Failed to start lookup [%s]:[%s]

Error message

Failed to start lookup [%s]:[%s]

What it means

startLookup() fails to start a lookup container. If the LookupExtractorFactory.start() returns false it logs the failure and returns null; if start() throws a RuntimeException it is wrapped in a ResponseException (RE) with the same 'Failed to start lookup' message including the lookup name and container.

Source

Thrown at server/src/main/java/org/apache/druid/query/lookup/LookupReferencesManager.java:589

    return successfulLookups;
  }

  @Nullable
  private Map.Entry<String, LookupExtractorFactoryContainer> startLookup(LookupBean lookupBean)
  {
    LookupExtractorFactoryContainer container = lookupBean.getContainer();
    LOG.info("Starting lookup [%s]:[%s]", lookupBean.getName(), container);
    try {
      if (container.getLookupExtractorFactory().start()) {
        LOG.info("Started lookup [%s]:[%s]", lookupBean.getName(), container);
        return new AbstractMap.SimpleImmutableEntry<>(lookupBean.getName(), container);
      } else {
        LOG.error("Failed to start lookup [%s]:[%s]", lookupBean.getName(), container);
        return null;
      }
    }
    catch (RuntimeException e) {
      throw new RE(e, "Failed to start lookup [%s]:[%s]", lookupBean.getName(), container);
    }
  }

  private LookupUpdateState atomicallyUpdateStateRef(Function<LookupUpdateState, LookupUpdateState> fn)
  {
    while (true) {
      LookupUpdateState old = stateRef.get();
      LookupUpdateState newState = fn.apply(old);
      if (stateRef.compareAndSet(old, newState)) {
        return newState;
      }
    }
  }

  private void dropContainer(LookupExtractorFactoryContainer container, String lookupName)
  {
    if (container != null) {
      LOG.debug("Removed lookup [%s] with spec [%s].", lookupName, container);

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Inspect the wrapped cause 'e' in the RE message for the factory's real failure reason.
2. Validate the lookup spec (host, port, connector config) before resubmitting.
3. Verify network connectivity from the Druid process to the lookup's backing store.
4. Check that the lookup name/bean is present and the container is in a startable state.

Example fix

// before: lookup spec with unreachable host
{"type":"redis","connectorConfig":{"host":"wrong-host","port":6379},...}
// after: corrected host
{"type":"redis","connectorConfig":{"host":"redis.internal","port":6379},...}

// validate lookup spec before submit
if (spec.getContainer().getLookupExtractorFactory() == null) throw new IllegalArgumentException("missing factory");
pingExternalStore(spec); // verify redis/kafka host:port reachable

try { manager.startLookups(Collections.singleton(name)); } catch (ResponseException e) { LOG.error("lookup %s failed to start: %s", name, e.getCause(), e); scheduleRetryWithBackoff(name); }

When it happens

Trigger: Calling startLookups() where the underlying factory's start() throws (e.g., bad lookup spec, unreachable external data source like Kafka/Redis, invalid config) or returns false (non-throwing failure).

Common situations: Misconfigured lookup spec (bad host/port in redis/kafka extraction namespace), network unavailability during startup, invalid serialization/deserialization settings in the lookup factory config.

Related errors

• start method returned false for lookup [%s]:[%s]
• %s: Malformed url for DruidNode [%s] and baseUrl [%s]
• Either uri xor uriPrefix required
• Cannot specify both versionRegex and fileRegex. versionRegex
• Cannot define both uri and fileRegex

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