apache/druid · critical · RuntimeException

File mapping failed.

Error message

File mapping failed.

What it means

GenericIndexed's mmapped variant wraps IOException from mapping the value file into memory and rethrows as RuntimeException('File mapping failed.', e). Mapped file access is mandatory for this representation, so mapping failure is fatal.

Solutions

1. Verify the segment file exists, is complete, and readable by the process; re-download or re-load the segment.
2. Increase OS limits (ulimit -n, vm.max_map_count) if many segments are mmapped.
3. Check underlying storage (disk/NFS) health and retry loading the segment; restart the node if the file handle state is broken.

if (!Files.isReadable(valueFilePath) || Files.size(valueFilePath) < expectedMinSize) {
  throw new SegmentNotLoadedException("value file missing or truncated: " + valueFilePath);
}

try { return mmappedGenericIndexed; } catch (RuntimeException e) {
  if (e.getCause() instanceof IOException) {
    // drop and re-download/reload the segment, or fail the query cleanly
  }
  throw e;
}

When it happens

Trigger: Constructing the mmapped GenericIndexed when the backing file cannot be mmap'd: file missing/unreadable, too many open mmaps (io_ionice/mmap limits), file truncated mid-read, or I/O errors.

Common situations: Segment files deleted or corrupted on disk while a query runs, exceeding OS mmap/open-file limits under heavy segment load, NFS/network storage flakiness.

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

• Cannot map region larger than %,d bytes
• Could not write [ ] bytes into smooshChannel.
• error closing…
• error closing…
• error closing…

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/data/GenericIndexed.java:793

      int numberOfFilesRequired = getNumberOfFilesRequired(elementsPerValueFile, numElements);
      ByteBuffer[] valueBuffersToUse = new ByteBuffer[numberOfFilesRequired];
      for (int i = 0; i < numberOfFilesRequired; i++) {
        // SegmentFileMapper.mapFile() contract guarantees that the valueBuffer's limit equals to capacity.
        ByteBuffer valueBuffer = fileMapper.mapFile(GenericIndexedWriter.generateValueFileName(columnName, i));
        valueBuffersToUse[i] = valueBuffer.asReadOnlyBuffer();
      }
      ByteBuffer headerBuffer = fileMapper.mapFile(GenericIndexedWriter.generateHeaderFileName(columnName));
      return new GenericIndexed.V2<>(
          valueBuffersToUse,
          headerBuffer,
          strategy,
          allowReverseLookup,
          logBaseTwoOfElementsPerValueFile,
          numElements
      );
    }
    catch (IOException e) {
      throw new RuntimeException("File mapping failed.", e);
    }
  }
}

View on GitHub (pinned to 9b90983fd2)