apache/druid · error · FileNotFoundException

File[%s] not found

Error message

File[%s] not found

What it means

FrameFile.open() memory-maps an existing frame file for reading. Before doing anything else it checks file.exists(); if the file is absent it throws FileNotFoundException naming the path. Frame files are typically written by durable storage or frame-writing stages and read later by frame-based query processing.

Source

Thrown at processing/src/main/java/org/apache/druid/frame/file/FrameFile.java:185

   *
   * Package-private because this method is intended for use in tests. In production, {@code maxMmapSize} is
   * set to {@link Integer#MAX_VALUE}.
   *  @param file        ƒrame file
   * @param maxMmapSize largest buffer to mmap at once
   * @param byteTracker
   * @param flags       optional flags
   */
  static FrameFile open(
      final File file,
      final int maxMmapSize,
      @Nullable final ByteTracker byteTracker,
      final Flag... flags
  ) throws IOException
  {
    final EnumSet<Flag> flagSet = flags.length == 0 ? EnumSet.noneOf(Flag.class) : EnumSet.copyOf(Arrays.asList(flags));

    if (!file.exists()) {
      throw new FileNotFoundException(StringUtils.format("File[%s] not found", file));
    }

    // Closer for mmap that is shared across all references: either footer only (if file size is larger
    // Integer.MAX_VALUE) or entire file (if file size is smaller than, or equal to, Integer.MAX_VALUE).
    Closeable sharedMapCloser = null;

    try (final RandomAccessFile randomAccessFile = new RandomAccessFile(file, "r")) {
      final long fileLength = randomAccessFile.length();

      // Verify minimum file length.
      if (fileLength <
          FrameFileWriter.MAGIC.length + FrameFileWriter.TRAILER_LENGTH + Byte.BYTES /* MARKER_NO_MORE_FRAMES */) {
        throw new IOE("File[%s] is too short (size[%,d])", file, fileLength);
      }

      // Verify magic.
      final byte[] buf = new byte[FrameFileWriter.TRAILER_LENGTH /* Larger than FrameFileWriter.MAGIC */];
      final Memory bufMemory = Memory.wrap(buf, ByteOrder.LITTLE_ENDIAN);

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Check the file exists at the given path (ls) and re-run the query to regenerate it if it was transient.
2. Verify durable storage configuration (druid.storage / local temp dirs) is consistent across nodes.
3. Disable or extend cleanup/retention so frames outlive the queries using them.
4. Retry the query; if the failure persists, check shared storage health.

Example fix

// before
FrameFile.open(new File("/druid/frames/partial-0000.frame"), Flag.REMOVE_FILE_ON_CLOSE); // ENOENT

// after
final File f = new File("/druid/frames/partial-0000.frame");
if (!f.exists()) {
  throw new IllegalStateException("Frame missing; re-run stage: " + f);
}
FrameFile.open(f, Flag.REMOVE_FILE_ON_CLOSE);

// Java: check existence before opening
final File frameFile = new File(path);
if (!frameFile.isFile()) {
  throw new FileNotFoundException("Frame file missing (may have been cleaned up): " + path);
}

try {
  FrameFile.open(file, flags);
} catch (FileNotFoundException e) {
  // regenerate or retry the stage that produced the frame
  throw new RetryableQueryException("Frame file gone: " + file, e);
}

When it happens

Trigger: Calling FrameFile.open(file, ...) with a path that does not exist on disk — e.g. frame file deleted between write and read, wrong directory in durable storage config, or a task re-reading frames after cleanup.

Common situations: Durable storage retention/cleanup removed the frame before the query finished reading it; configured storage directory differs across cluster nodes (shared storage misconfig); restart wiped a local temp frame directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• File[%s] is too short (size[%,d])
• Input stream is null
• Exception while writing distribution file for interval [%s],
• Error while reading distribution for interval [%s], task [%s
• Read 0 bytes from segmentDir[%s]

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