{"record":{"id":"cbf391aca8ba04b4","repo":"apache/druid","slug":"lookup-s-is-not-loaded","errorCode":null,"errorMessage":"Lookup[%s] is not loaded","messagePattern":"Lookup\\[(.+?)\\] is not loaded","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"multi-stage-query/src/main/java/org/apache/druid/msq/input/lookup/LookupInputSliceReader.java","lineNumber":77,"sourceCode":"  @Override\n  public PhysicalInputSlice attach(\n      final int inputNumber,\n      final InputSlice slice,\n      final CounterTracker counters,\n      final Consumer<Throwable> warningPublisher\n  )\n  {\n    final String lookupName = ((LookupInputSlice) slice).getLookupName();\n\n    final Iterable<Segment> segments =\n        segmentWrangler.getSegmentsForIntervals(\n            new LookupDataSource(lookupName),\n            Intervals.ONLY_ETERNITY\n        );\n\n    final Iterator<Segment> segmentIterator = segments.iterator();\n    if (!segmentIterator.hasNext()) {\n      throw new ISE(\"Lookup[%s] is not loaded\", lookupName);\n    }\n\n    final Segment segment = segmentIterator.next();\n    if (segmentIterator.hasNext()) {\n      // LookupSegmentWrangler always returns zero or one segments, so this code block can't\n      // happen. That being said: we'll program defensively anyway.\n      CloseableUtils.closeAndSuppressExceptions(\n          segment,\n          e -> log.warn(e, \"Failed to close segment for lookup[%s]\", lookupName)\n      );\n      throw new ISE(\"Lookup[%s] has multiple segments; cannot read\", lookupName);\n    }\n\n    final LoadableSegment loadableSegment = AdaptedLoadableSegment.fromUnmanagedSegment(\n        segment,\n        new SegmentDescriptor(Intervals.ETERNITY, \"0\", 0),\n        StringUtils.format(\"lookup[%s]\", lookupName),\n        counters.channel(CounterNames.inputChannel(inputNumber))","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/multi-stage-query/src/main/java/org/apache/druid/msq/input/lookup/LookupInputSliceReader.java#L59-L95","documentation":"When an MSQ stage reads from a lookup datasource, LookupInputSliceReader.attach fetches the lookup's segments through a segment wrangler. If the wrangler returns zero segments, the lookup data is not loaded anywhere in the cluster, so reading is impossible and this ISE is thrown naming the lookup.","triggerScenarios":"attach() is called for a lookupName whose LookupSegmentWrangler response contains no segments - i.e. the lookup is configured on the cluster but no node currently holds a loaded LookupSegment for it.","commonSituations":"Query references a lookup name with a typo; lookup was configured but never populated (no init script/entry loaded); lookup was dropped or its load failed after a broker restart; lookup config replication lag on a fresh cluster.","solutions":["Verify the lookup name exists in cluster lookup configuration (GET /druid/coordinator/v1/lookups/status).","Load or re-populate the lookup by posting the lookup config to /druid/coordinator/v1/lookups and waiting for it to report loaded on all nodes.","Check lookup node logs for load failures (memory limits, TieredLookupConfig errors).","Fix typos in the LOOKUP datasource name in the SQL query."],"exampleFix":"// before\nSELECT * FROM src WHERE v = LOOKUP(dim, 'missing_lookup')\n// after: ensure the lookup is loaded first, e.g. via coordinator API\n// POST /druid/coordinator/v1/lookups/config with \"__default\": {\"missing_lookup\": {...}}\nSELECT * FROM src WHERE v = LOOKUP(dim, 'missing_lookup')","handlingStrategy":"validation","validationCode":"LookupStatus status = client.lookupStatus(lookupName); // coordinator API\nif (status == null || !status.isLoaded()) {\n  throw new IllegalStateException(\"Lookup not loaded: \" + lookupName);\n}","typeGuard":null,"tryCatchPattern":"try {\n  reader.attach(buffer);\n} catch (IllegalStateException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"is not loaded\")) {\n    throw new QueryException(\"Lookup not loaded: \" + lookupName + \"; check /druid/coordinator/v1/lookups/status\", e);\n  }\n  throw e;\n}","preventionTips":["Verify lookup status via the coordinator API before running LOOKUP queries.","Avoid lookup name typos by centralizing lookup names in config.","Monitor lookup load failures on lookup-enabled tiers."],"tags":["msq","lookup","not-loaded","resource-not-found"],"backgroundTag":"resource-not-found","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"}