{"record":{"id":"8cd7066738943fb1","repo":"apache/druid","slug":"start-method-returned-false-for-lookup-s-s","errorCode":null,"errorMessage":"start method returned false for lookup [%s]:[%s]","messagePattern":"start method returned false for lookup \\[(.+?)\\]:\\[(.+?)\\]","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"server/src/main/java/org/apache/druid/query/lookup/LookupReferencesManager.java","lineNumber":656,"sourceCode":"\n    @Override\n    public void handle(Map<String, LookupExtractorFactoryContainer> lookupMap, LookupReferencesManager manager)\n        throws Exception\n    {\n      LookupExtractorFactoryContainer old = lookupMap.get(lookupName);\n      if (old != null && !lookupExtractorFactoryContainer.replaces(old)) {\n        LOG.warn(\n            \"got notice to load lookup [%s] that can't replace existing [%s].\",\n            lookupExtractorFactoryContainer,\n            old\n        );\n        return;\n      }\n\n      RetryUtils.retry(\n          () -> {\n            if (!lookupExtractorFactoryContainer.getLookupExtractorFactory().start()) {\n              throw new ISE(\n                  \"start method returned false for lookup [%s]:[%s]\",\n                  lookupName,\n                  lookupExtractorFactoryContainer\n              );\n            }\n            return null;\n          },\n          e -> true,\n          startRetries\n      );\n      /*\n       if new container is initailized then add it to manager to start serving immediately.\n       if old container is null then it is fresh load, we can skip waiting for initialization and add the container to registry first. Esp for MSQ workers.\n       */\n      if (old == null || lookupExtractorFactoryContainer.getLookupExtractorFactory().isInitialized()) {\n        old = lookupMap.put(lookupName, lookupExtractorFactoryContainer);\n        LOG.debug(\"Loaded lookup [%s] with spec [%s].\", lookupName, lookupExtractorFactoryContainer);\n        manager.dropContainer(old, lookupName);","sourceCodeStart":638,"sourceCodeEnd":674,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/query/lookup/LookupReferencesManager.java#L638-L674","documentation":"Inside handle()'s RetryUtils.retry block, a lookup's LookupExtractorFactory.start() returning false throws an IllegalStateException, causing the retry policy to re-attempt loading the lookup until retries are exhausted.","triggerScenarios":"A LoadNotice is handled and the factory's start() returns false (soft failure, e.g., external data source not yet reachable); retries continue until start() succeeds or retry limits are hit.","commonSituations":"Transient network outages to Kafka/Redis/JDBC sources during broker startup; wrong lookup spec credentials; prolonged dependency unavailability causing final failure after retries.","solutions":["Enable/inspect factory start() logging to see why it returns false.","Fix the underlying connectivity or spec problem so start() can succeed.","Increase lookup start retry settings (lookupStartRetries / RetryUtils config) for known-flaky sources.","Verify the lookup's external dependency is healthy and reachable from the Druid node."],"exampleFix":"// before: transient failing start\n{\"type\":\"kafkaLookup\",...} // kafka down -> start() false\n// after: add retry budget via lookup config\n// POST lookup with lookupStartRetries configured, or fix kafka connectivity first","handlingStrategy":"retry","validationCode":"// probe the external dependency before issuing a load notice\nif (!isReachable(lookupSpec.getConnectorHost(), lookupSpec.getConnectorPort())) { delayLoadNotice(lookupSpec); }","typeGuard":null,"tryCatchPattern":"try { manager.add(name, container); } catch (Exception e) { /* handle() retries internally; surface final failure */ LOG.error(\"lookup %s start failed after retries\", name, e); alertOps(name); }","preventionTips":["Keep lookup start retries configured for transient sources","Monitor external dependencies (Kafka/Redis/JDBC) health","Log factory.start() false-returns with enough detail","Gate bulk loads on dependency readiness checks"],"tags":["lookup","retry","startup-failure","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"}