{"record":{"id":"8424864236092826","repo":"apache/druid","slug":"file-mapping-failed","errorCode":null,"errorMessage":"File mapping failed.","messagePattern":"File mapping failed\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"processing/src/main/java/org/apache/druid/segment/data/GenericIndexed.java","lineNumber":793,"sourceCode":"      int numberOfFilesRequired = getNumberOfFilesRequired(elementsPerValueFile, numElements);\n      ByteBuffer[] valueBuffersToUse = new ByteBuffer[numberOfFilesRequired];\n      for (int i = 0; i < numberOfFilesRequired; i++) {\n        // SegmentFileMapper.mapFile() contract guarantees that the valueBuffer's limit equals to capacity.\n        ByteBuffer valueBuffer = fileMapper.mapFile(GenericIndexedWriter.generateValueFileName(columnName, i));\n        valueBuffersToUse[i] = valueBuffer.asReadOnlyBuffer();\n      }\n      ByteBuffer headerBuffer = fileMapper.mapFile(GenericIndexedWriter.generateHeaderFileName(columnName));\n      return new GenericIndexed.V2<>(\n          valueBuffersToUse,\n          headerBuffer,\n          strategy,\n          allowReverseLookup,\n          logBaseTwoOfElementsPerValueFile,\n          numElements\n      );\n    }\n    catch (IOException e) {\n      throw new RuntimeException(\"File mapping failed.\", e);\n    }\n  }\n}\n","sourceCodeStart":775,"sourceCodeEnd":797,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/segment/data/GenericIndexed.java#L775-L797","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the segment file exists, is complete, and readable by the process; re-download or re-load the segment.","Increase OS limits (ulimit -n, vm.max_map_count) if many segments are mmapped.","Check underlying storage (disk/NFS) health and retry loading the segment; restart the node if the file handle state is broken."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if (!Files.isReadable(valueFilePath) || Files.size(valueFilePath) < expectedMinSize) {\n  throw new SegmentNotLoadedException(\"value file missing or truncated: \" + valueFilePath);\n}","typeGuard":null,"tryCatchPattern":"try { return mmappedGenericIndexed; } catch (RuntimeException e) {\n  if (e.getCause() instanceof IOException) {\n    // drop and re-download/reload the segment, or fail the query cleanly\n  }\n  throw e;\n}","preventionTips":["Monitor disk integrity and re-download corrupt segments","Raise vm.max_map_count and ulimit -n on nodes loading many segments","Avoid deleting segment files while brokers/historical nodes hold them open"],"tags":["java","mmap","io"],"backgroundTag":"file-read-failed","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}