apache/druid · error · IllegalStateException

Exception during reading lookups from [%s]

Error message

Exception during reading lookups from [%s]

What it means

LookupSnapshotTaker.pullExistingSnapshot deserializes the persisted lookup tier snapshot file (JSON list of LookupBean) with the ObjectMapper. If reading the file raises IOException (missing file access, corrupt snapshot, unreadable permissions), it wraps it in this ISE.

Source

Thrown at processing/src/main/java/org/apache/druid/query/lookup/LookupSnapshotTaker.java:76

  public synchronized List<LookupBean> pullExistingSnapshot(final String tier)
  {
    final File persistFile = getPersistFile(tier);

    List<LookupBean> lookupBeanList;
    try {
      if (!persistFile.isFile()) {
        LOGGER.warn("could not find any snapshot file under working directory [%s]", persistDirectory);
        return Collections.emptyList();
      } else if (persistFile.length() == 0) {
        LOGGER.warn("found empty file no lookups to load from [%s]", persistFile.getAbsolutePath());
        return Collections.emptyList();
      }
      lookupBeanList = objectMapper.readValue(persistFile, new TypeReference<>() {});
      return lookupBeanList;
    }
    catch (IOException e) {
      throw new ISE(e, "Exception during reading lookups from [%s]", persistFile.getAbsolutePath());
    }
  }

  public synchronized void takeSnapshot(String tier, List<LookupBean> lookups)
  {
    final File persistFile = getPersistFile(tier);

    try {
      FileUtils.writeAtomically(
          persistFile,
          out -> {
            objectMapper.writeValue(out, lookups);
            return null;
          }
      );
    }
    catch (IOException e) {
      throw new ISE(e, "Exception during serialization of lookups using file [%s]", persistFile.getAbsolutePath());

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Inspect the snapshot file at the reported path and delete/replace the corrupt file so a fresh snapshot can be taken
2. Fix filesystem permissions/ownership on the persistence directory for the Druid process user
3. Verify disk health and available space; check logs for earlier takeSnapshot failures

Example fix

// before
// corrupt snapshot file causes ISE at startup
// after
rm /path/to/lookups/<tier>.json && restart node // snapshot recreated from cluster state

File f = snapshotTaker.getPersistFile(tier);
if (!f.isFile()) return Collections.emptyList();
if (!f.canRead()) throw new IllegalStateException("No read permission on " + f);

try {
  return snapshotTaker.pullExistingSnapshot(tier);
} catch (ISE e) {
  if (e.getMessage().startsWith("Exception during reading lookups")) {
    logger.warn(e, "Snapshot unreadable, starting with empty lookup set");
    return Collections.emptyList();
  }
  throw e;
}

When it happens

Trigger: Calling pullExistingSnapshot (via actualList) when getPersistFile(tier) exists but objectMapper.readValue throws IOException — e.g. truncated/corrupt JSON snapshot, permission denied, or the file disappearing between existence check and read.

Common situations: Druid nodes restoring lookups at startup after an unclean shutdown that left a partial snapshot, wrong directory permissions on the lookup persistence path, or filesystem errors on the tier's snapshot file.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Exception during serialization of lookups using file [%s]
• Input stream is null
• Failed to fetch google cloud storage object from bucket [%s]
• Failed to fetch google cloud storage object from bucket [%s]
• Failed to stream logs from: %s

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