{"record":{"id":"526ff4683d81a8c2","repo":"apache/druid","slug":"failed-to-start-lookup-s-s","errorCode":null,"errorMessage":"Failed to start lookup [%s]:[%s]","messagePattern":"Failed to start lookup \\[(.+?)\\]:\\[(.+?)\\]","errorType":"exception","errorClass":"QueryException (RE)","httpStatus":null,"severity":"error","filePath":"server/src/main/java/org/apache/druid/query/lookup/LookupReferencesManager.java","lineNumber":589,"sourceCode":"    return successfulLookups;\n  }\n\n  @Nullable\n  private Map.Entry<String, LookupExtractorFactoryContainer> startLookup(LookupBean lookupBean)\n  {\n    LookupExtractorFactoryContainer container = lookupBean.getContainer();\n    LOG.info(\"Starting lookup [%s]:[%s]\", lookupBean.getName(), container);\n    try {\n      if (container.getLookupExtractorFactory().start()) {\n        LOG.info(\"Started lookup [%s]:[%s]\", lookupBean.getName(), container);\n        return new AbstractMap.SimpleImmutableEntry<>(lookupBean.getName(), container);\n      } else {\n        LOG.error(\"Failed to start lookup [%s]:[%s]\", lookupBean.getName(), container);\n        return null;\n      }\n    }\n    catch (RuntimeException e) {\n      throw new RE(e, \"Failed to start lookup [%s]:[%s]\", lookupBean.getName(), container);\n    }\n  }\n\n  private LookupUpdateState atomicallyUpdateStateRef(Function<LookupUpdateState, LookupUpdateState> fn)\n  {\n    while (true) {\n      LookupUpdateState old = stateRef.get();\n      LookupUpdateState newState = fn.apply(old);\n      if (stateRef.compareAndSet(old, newState)) {\n        return newState;\n      }\n    }\n  }\n\n  private void dropContainer(LookupExtractorFactoryContainer container, String lookupName)\n  {\n    if (container != null) {\n      LOG.debug(\"Removed lookup [%s] with spec [%s].\", lookupName, container);","sourceCodeStart":571,"sourceCodeEnd":607,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/query/lookup/LookupReferencesManager.java#L571-L607","documentation":"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.","triggerScenarios":"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).","commonSituations":"Misconfigured lookup spec (bad host/port in redis/kafka extraction namespace), network unavailability during startup, invalid serialization/deserialization settings in the lookup factory config.","solutions":["Inspect the wrapped cause 'e' in the RE message for the factory's real failure reason.","Validate the lookup spec (host, port, connector config) before resubmitting.","Verify network connectivity from the Druid process to the lookup's backing store.","Check that the lookup name/bean is present and the container is in a startable state."],"exampleFix":"// before: lookup spec with unreachable host\n{\"type\":\"redis\",\"connectorConfig\":{\"host\":\"wrong-host\",\"port\":6379},...}\n// after: corrected host\n{\"type\":\"redis\",\"connectorConfig\":{\"host\":\"redis.internal\",\"port\":6379},...}","handlingStrategy":"retry","validationCode":"// validate lookup spec before submit\nif (spec.getContainer().getLookupExtractorFactory() == null) throw new IllegalArgumentException(\"missing factory\");\npingExternalStore(spec); // verify redis/kafka host:port reachable","typeGuard":null,"tryCatchPattern":"try { manager.startLookups(Collections.singleton(name)); } catch (ResponseException e) { LOG.error(\"lookup %s failed to start: %s\", name, e.getCause(), e); scheduleRetryWithBackoff(name); }","preventionTips":["Validate lookup specs (host, port, credentials) before submission","Check connectivity to lookup backing stores during rollout","Include the wrapped cause when logging to find the root failure","Use lookup start retry configuration for transient dependencies"],"tags":["lookup","startup-failure","configuration","network"],"backgroundTag":"api-error-response","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}