{"record":{"id":"2948e894ef90fddc","repo":"apache/hadoop","slug":"incompatible-tfile-fileversion","errorCode":null,"errorMessage":"Incompatible TFile fileVersion.","messagePattern":"Incompatible TFile fileVersion\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java","lineNumber":2076,"sourceCode":"    final Version version;\n    private long recordCount;\n    private final String strComparator;\n    private final BytesComparator comparator;\n\n    // ctor for writes\n    TFileMeta(String comparator, Configuration conf) {\n      // set fileVersion to API version when we create it.\n      version = TFile.API_VERSION;\n      recordCount = 0;\n      strComparator = (comparator == null) ? \"\" : comparator;\n      this.comparator = makeComparator(strComparator, conf);\n    }\n\n    // ctor for reads\n    TFileMeta(DataInput in, Configuration conf) throws IOException {\n      version = new Version(in);\n      if (!version.compatibleWith(TFile.API_VERSION)) {\n        throw new RuntimeException(\"Incompatible TFile fileVersion.\");\n      }\n      recordCount = Utils.readVLong(in);\n      strComparator = Utils.readString(in, MAX_COMPARATOR_LENGTH);\n      comparator = makeComparator(strComparator, conf);\n    }\n\n    static BytesComparator makeComparator(String comparator) {\n      return makeComparator(comparator, new Configuration());\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    static BytesComparator makeComparator(String comparator,\n        Configuration conf) {\n      if (comparator.length() == 0) {\n        // unsorted keys\n        return null;\n      }\n      if (comparator.equals(COMPARATOR_MEMCMP)) {","sourceCodeStart":2058,"sourceCodeEnd":2094,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java#L2058-L2094","documentation":"RuntimeException from the TFileMeta read constructor: the Version parsed from the file header fails version.compatibleWith(TFile.API_VERSION) (currently 1.0). TFile deliberately gates reads on version compatibility so newer or incompatible formats fail fast at open time instead of misparsing later.","triggerScenarios":"new TFile.Reader(fsdis, fileLength, conf) on a file whose embedded major/minor version is not compatible with 1.0: files produced by a newer TFile implementation, experimental formats, or a stream position/length that is wrong so the version short-pair decodes garbage.","commonSituations":"Rolling upgrades where writer nodes run a newer Hadoop than readers, copying files written by downstream forks that bumped the version, or passing a wrong fileLength / already-consumed FSDataInputStream so the constructor reads the version from the wrong offset.","solutions":["Read and write with compatible Hadoop versions: pin the cluster to one version through the upgrade, or upgrade readers first.","Verify the stream position (seek(0)) and fileLength passed to the Reader constructor match the actual file.","If the file legitimately comes from a newer format, convert it on a node that can read it (e.g. dump with TFileDumper and rewrite) before handing it to older readers."],"exampleFix":"// before\nTFile.Reader r = new TFile.Reader(in, len, conf); // may throw on version skew\n// after\ntry {\n  TFile.Reader r = new TFile.Reader(in, len, conf);\n} catch (RuntimeException e) {\n  if (e.getMessage().contains(\"fileVersion\")) { /* writer/reader skew: convert or upgrade */ }\n  else throw e;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  TFile.Reader r = new TFile.Reader(fsdis, fileLength, conf);\n} catch (RuntimeException e) {\n  if (String.valueOf(e.getMessage()).contains(\"fileVersion\")) {\n    // version skew: route to conversion or fail with upgrade guidance\n  } else { throw e; }\n}","preventionTips":["Keep writer and reader Hadoop versions aligned across rolling upgrades (readers first).","Always seek(0) the stream and pass the exact file length to the Reader.","Store the producing version in your file catalog to detect skew before opening."],"tags":["tfile","hadoop-common","version","compatibility","header"],"backgroundTag":"file-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}