{"record":{"id":"8bb7902812ab73d2","repo":"apache/iceberg","slug":"failed-to-update-version-hint","errorCode":null,"errorMessage":"Failed to update version hint","messagePattern":"Failed to update version hint","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/apache/iceberg/hadoop/HadoopTableOperations.java","lineNumber":302,"sourceCode":"    }\n  }\n\n  @VisibleForTesting\n  Path versionHintFile() {\n    return metadataPath(Util.VERSION_HINT_FILENAME);\n  }\n\n  private void writeVersionHint(int versionToWrite) {\n    Path versionHintFile = versionHintFile();\n    FileSystem fs = getFileSystem(versionHintFile, conf);\n\n    try {\n      Path tempVersionHintFile = metadataPath(UUID.randomUUID() + \"-version-hint.temp\");\n      writeVersionToPath(fs, tempVersionHintFile, versionToWrite);\n      fs.delete(versionHintFile, false /* recursive delete */);\n      fs.rename(tempVersionHintFile, versionHintFile);\n    } catch (IOException e) {\n      LOG.warn(\"Failed to update version hint\", e);\n    }\n  }\n\n  private void writeVersionToPath(FileSystem fs, Path path, int versionToWrite) throws IOException {\n    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\", \"\"));","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/hadoop/HadoopTableOperations.java#L284-L320","documentation":"HadoopTableOperations maintains a 'version-hint.text' file pointing at the latest metadata version. writeVersionHint catches any IOException during the temp-file write/delete/rename sequence and only logs this WARN — the table commit itself has already succeeded; only the convenience hint file may be stale.","triggerScenarios":"commit() calls writeVersionHint after writing new metadata.json; fs.delete/rename/create on the hint file fails (permissions, HDFS lease/recovery, S3 consistency or throttling, concurrent commits racing on the same hint file).","commonSituations":"Read-only or restricted-permission metadata directory; concurrent writers causing rename races; object stores with eventual consistency or transient 503s; HDFS safemode/under-replication during commit.","solutions":["Safe to ignore for correctness — readers should not depend on version-hint.text; verify the actual metadata.json exists.","Fix filesystem permissions to allow the writer to delete/rename files in the metadata directory.","Reduce concurrent-commit races on the same table; retry the commit if hint freshness matters.","If a tool relies on the hint file, refresh it manually or re-commit to regenerate it."],"exampleFix":"// before\nPath hint = metadataPath(\"version-hint.text\");\nfs.rename(temp, hint); // IOException -> warn only\n// after\n// ensure writer has write access:\nhdfs dfs -chmod 770 /warehouse/db/table/metadata\n// then re-run the commit to rewrite the hint","handlingStrategy":"fallback","validationCode":"// verify metadata dir is writable by the committing user\n// hadoop fs -touchz /warehouse/db/table/metadata/.probe","typeGuard":null,"tryCatchPattern":"try {\n  table.refresh();\n} catch (Exception e) {\n  // version-hint warn is benign; commit result visible via metadata.json listing\n}","preventionTips":["Ensure write/delete permissions on the table metadata directory.","Avoid many concurrent committers on the same Hadoop table.","Do not build tooling that depends on version-hint.text for correctness.","Retry commits on transient object-store/hdfs errors."],"tags":["hadoop","commit","version-hint","io"],"backgroundTag":"file-write-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"}