{"record":{"id":"bd06772262de6add","repo":"apache/iceberg","slug":"error-reading-version-hint-file","errorCode":null,"errorMessage":"Error reading version hint file {}","messagePattern":"Error reading version hint file (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/apache/iceberg/hadoop/HadoopTableOperations.java","lineNumber":325,"sourceCode":"    try (FSDataOutputStream out = fs.create(path, false /* overwrite */)) {\n      out.write(String.valueOf(versionToWrite).getBytes(StandardCharsets.UTF_8));\n    }\n  }\n\n  @VisibleForTesting\n  int findVersion() {\n    Path versionHintFile = versionHintFile();\n    FileSystem fs = getFileSystem(versionHintFile, conf);\n\n    try (InputStreamReader fsr =\n            new InputStreamReader(fs.open(versionHintFile), StandardCharsets.UTF_8);\n        BufferedReader in = new BufferedReader(fsr)) {\n      return Integer.parseInt(in.readLine().replace(\"\\n\", \"\"));\n\n    } catch (Exception e) {\n      try {\n        if (fs.exists(metadataRoot())) {\n          LOG.warn(\"Error reading version hint file {}\", versionHintFile, e);\n        } else {\n          LOG.debug(\"Metadata for table not found in directory {}\", metadataRoot(), e);\n          return 0;\n        }\n\n        // List the metadata directory to find the version files, and try to recover the max\n        // available version\n        FileStatus[] files =\n            fs.listStatus(\n                metadataRoot(), name -> VERSION_PATTERN.matcher(name.getName()).matches());\n        int maxVersion = 0;\n\n        for (FileStatus file : files) {\n          int currentVersion = version(file.getPath().getName());\n          if (currentVersion > maxVersion && getMetadataFile(currentVersion) != null) {\n            maxVersion = currentVersion;\n          }\n        }","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/hadoop/HadoopTableOperations.java#L307-L343","documentation":"HadoopTableOperations.findVersion() reads the version-hint.text file to determine the current metadata version. When parsing fails (unreadable, corrupted, or missing content), it logs this warning and attempts recovery by listing the metadata directory for version files and returning the max. It is a warning, not a thrown exception; the table version is recovered or 0 is returned.","triggerScenarios":"Calling HadoopTableOperations.ver()/findVersion() when version-hint.text cannot be read: the file exists but is empty, contains non-numeric text, was partially written, or the underlying FileSystem read throws an IOException while metadataRoot() still exists.","commonSituations":"Manually copied or synced table locations (e.g. S3/HDFS distcp) where version-hint.text was missed or truncated; concurrent writer racing a reader during table creation; HDFS read errors or NameNode failover mid-read.","solutions":["Check that version-hint.text exists and contains a single integer line at the table metadata root","Restore the file from a healthy replica of the table location","Recreate or repair the version hint by writing the current max metadata version number to version-hint.text","Verify filesystem connectivity/permissions so the read does not fail","Upgrade Iceberg; newer versions improve version-hint recovery robustness"],"exampleFix":"// before (corrupted version-hint.text)\ncat /table/metadata/version-hint.text  # -> empty or garbage\n// after\necho 12 > /table/metadata/version-hint.text  # matches v12.metadata.json","handlingStrategy":"fallback","validationCode":"Path vh = new Path(metadataRoot, \"version-hint.text\");\nif (!fs.exists(vh)) { /* repair before opening table */ }\ntry (FSDataInputStream in = fs.open(vh)) {\n  Integer.parseInt(in.readLine().trim()); // must parse as int\n}","typeGuard":null,"tryCatchPattern":"try {\n  int v = ops.currentVersion();\n} catch (RuntimeException e) {\n  // recovery already logs; reload table or repair version-hint.text\n}","preventionTips":["Verify version-hint.text exists and contains a single integer when copying tables","Never hand-edit metadata; use Iceberg APIs to rewrite metadata","Avoid concurrent writers truncating version-hint.text via single-writer discipline","Monitor for this warning after storage migrations"],"tags":["hadoop","io","version-hint","recovery"],"backgroundTag":"file-read-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}