{"record":{"id":"b305fdd14693c925","repo":"apache/druid","slug":"file-s-is-not-a-frame-file","errorCode":null,"errorMessage":"File[%s] is not a frame file","messagePattern":"File\\[(.+?)\\] is not a frame file","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/frame/file/FrameFile.java","lineNumber":207,"sourceCode":"    // Integer.MAX_VALUE) or entire file (if file size is smaller than, or equal to, Integer.MAX_VALUE).\n    Closeable sharedMapCloser = null;\n\n    try (final RandomAccessFile randomAccessFile = new RandomAccessFile(file, \"r\")) {\n      final long fileLength = randomAccessFile.length();\n\n      // Verify minimum file length.\n      if (fileLength <\n          FrameFileWriter.MAGIC.length + FrameFileWriter.TRAILER_LENGTH + Byte.BYTES /* MARKER_NO_MORE_FRAMES */) {\n        throw new IOE(\"File[%s] is too short (size[%,d])\", file, fileLength);\n      }\n\n      // Verify magic.\n      final byte[] buf = new byte[FrameFileWriter.TRAILER_LENGTH /* Larger than FrameFileWriter.MAGIC */];\n      final Memory bufMemory = Memory.wrap(buf, ByteOrder.LITTLE_ENDIAN);\n      randomAccessFile.readFully(buf, 0, FrameFileWriter.MAGIC.length);\n\n      if (!bufMemory.equalTo(0, Memory.wrap(FrameFileWriter.MAGIC), 0, FrameFileWriter.MAGIC.length)) {\n        throw new IOE(\"File[%s] is not a frame file\", file);\n      }\n\n      // Read number of frames and partitions.\n      randomAccessFile.seek(fileLength - FrameFileWriter.TRAILER_LENGTH);\n      randomAccessFile.readFully(buf, 0, FrameFileWriter.TRAILER_LENGTH);\n\n      final int footerLength = bufMemory.getInt(Integer.BYTES * 2L);\n      if (footerLength < 0) {\n        throw new ISE(\"Negative-size footer. Corrupt or truncated file[%s]?\", file);\n      } else if (footerLength > fileLength) {\n        throw new ISE(\"Oversize footer. Corrupt or truncated file[%s]?\", file);\n      }\n\n      final Memory wholeFileMemory;\n      final Memory footerMemory;\n\n      if (fileLength <= maxMmapSize) {\n        // Map entire file, use region for footer.","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/frame/file/FrameFile.java#L189-L225","documentation":"FrameFile.open validates that the target file begins with the FrameFileWriter magic bytes before reading any structure. If the first MAGIC.length bytes do not match, the file was not produced by the frame file writer (or its header was overwritten/truncated). The library throws this immediately to fail fast on non-frame input.","triggerScenarios":"Calling FrameFile.open on a file that is empty, is a different file format, was truncated so the header bytes are missing, or whose leading bytes were modified after writing.","commonSituations":"Pointing a segment/frame reader at a log, JSON, or partially-written file; a job crashed mid-write leaving a zero-byte file; copying files with truncation; confusing two similarly-named output files.","solutions":["Verify the file path points to an actual frame file produced by FrameFileWriter (check the writer job output).","Check the file size — a valid frame file must be at least TRAILER_LENGTH + header bytes; re-run the producing job if it is 0 or tiny.","If the file should be a frame file, re-generate it; corruption of the header is not recoverable.","Add a file-format/extension sanity check before opening files from user-supplied paths."],"exampleFix":"// before\nFrameFile.open(new File(\"output.json\"), maxMmapSize);\n// after\nFile f = new File(\"output.frame\");\nif (f.length() < FrameFileWriter.TRAILER_LENGTH + FrameFileWriter.MAGIC.length) {\n  throw new IllegalStateException(\"Not a frame file (too small): \" + f);\n}\nFrameFile.open(f, maxMmapSize);","handlingStrategy":"validation","validationCode":"if (file == null || file.length() < FrameFileWriter.TRAILER_LENGTH) {\n  throw new IllegalArgumentException(\"Not a frame file (missing header/trailer): \" + file);\n}","typeGuard":"static boolean looksLikeFrameFile(File f) {\n  return f.isFile() && f.length() >= FrameFileWriter.TRAILER_LENGTH;\n}","tryCatchPattern":"try {\n  FrameFile.open(file, maxMmapSize);\n} catch (IOException e) {\n  // includes 'is not a frame file': regenerate or re-point to correct output\n  throw new UncheckedIOException(\"Invalid frame file: \" + file, e);\n}","preventionTips":["Only open files produced by FrameFileWriter; keep frame files in dedicated directories with a distinct extension.","Check the producing task/segment status before reading its output.","Use binary-safe transfers and verify sizes/checksums after copying.","Never read a frame file while its writer is still running."],"tags":["io","file-validation","druid"],"backgroundTag":"file-not-found","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"}