apache/druid · error · IllegalStateException

Exception during serialization of lookups using file [%s]

Error message

Exception during serialization of lookups using file [%s]

What it means

LookupSnapshotTaker.takeSnapshot serializes the current lookup list to the tier snapshot file via ObjectMapper.writeValue inside a retry/IO action. An IOException during that write (disk full, permissions, I/O failure) is wrapped in this ISE naming the target file.

Source

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

      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());
    }
  }

  @VisibleForTesting
  File getPersistFile(final String tier)
  {
    return new File(persistDirectory, StringUtils.format("%s.%s", tier, PERSIST_FILE_SUFFIX));
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

Check disk space and free space on the partition holding the snapshot directory
Fix write permissions on the persistence directory for the Druid process user
Ensure the parent directory exists (create it) and check filesystem mount status (read-only mounts)

Example fix

// before
// snapshot write fails on read-only mount
// after
mount -o remount,rw /path/to/persistence && chmod u+w /path/to/persistence

Defensive patterns

Strategy: try-catch

Validate before calling

File dir = persistFile.getParentFile();
if (dir == null || !dir.isDirectory() || !dir.canWrite()) {
  throw new IllegalStateException("Lookup snapshot directory not writable: " + dir);
}
if (dir.getUsableSpace() < MIN_FREE_BYTES) {
  throw new IllegalStateException("Low disk space for lookup snapshot");
}

Try / catch

try {
  snapshotTaker.takeSnapshot(tier, lookups);
} catch (ISE e) {
  if (e.getMessage().startsWith("Exception during serialization")) {
    logger.error(e.getCause(), "Failed to persist lookup snapshot; lookups remain in memory");
  } else throw e;
}

Prevention

Alert on low disk space for the lookup persistence path
Ensure the Druid process has write permission on the snapshot directory
Verify the mount is not read-only before nodes join the cluster

When it happens

Trigger: Calling takeSnapshot when writing the JSON snapshot to getPersistFile(tier) fails with IOException — read-only filesystem, disk full, missing parent directory, or an error from the underlying output stream.

Common situations: Lookup snapshots cannot be persisted on nodes with a full or read-only disk, after directory removal, or when the Druid process lacks write permission to the lookup persistence path.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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