apache/iceberg · warning

Failed to update version hint

Error message

Failed to update version hint

What it means

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.

Solutions

1. Safe to ignore for correctness — readers should not depend on version-hint.text; verify the actual metadata.json exists.
2. Fix filesystem permissions to allow the writer to delete/rename files in the metadata directory.
3. Reduce concurrent-commit races on the same table; retry the commit if hint freshness matters.
4. If a tool relies on the hint file, refresh it manually or re-commit to regenerate it.

Example fix

// before
Path hint = metadataPath("version-hint.text");
fs.rename(temp, hint); // IOException -> warn only
// after
// ensure writer has write access:
hdfs dfs -chmod 770 /warehouse/db/table/metadata
// then re-run the commit to rewrite the hint

// verify metadata dir is writable by the committing user
// hadoop fs -touchz /warehouse/db/table/metadata/.probe

try {
  table.refresh();
} catch (Exception e) {
  // version-hint warn is benign; commit result visible via metadata.json listing
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Error reading version hint file
• Error trying to recover the latest version number for
• Create namespace failed
• Failed to create file
• Failed to create Parquet input file for

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/8bb7902812ab73d2. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/hadoop/HadoopTableOperations.java:302

    }
  }

  @VisibleForTesting
  Path versionHintFile() {
    return metadataPath(Util.VERSION_HINT_FILENAME);
  }

  private void writeVersionHint(int versionToWrite) {
    Path versionHintFile = versionHintFile();
    FileSystem fs = getFileSystem(versionHintFile, conf);

    try {
      Path tempVersionHintFile = metadataPath(UUID.randomUUID() + "-version-hint.temp");
      writeVersionToPath(fs, tempVersionHintFile, versionToWrite);
      fs.delete(versionHintFile, false /* recursive delete */);
      fs.rename(tempVersionHintFile, versionHintFile);
    } catch (IOException e) {
      LOG.warn("Failed to update version hint", e);
    }
  }

  private void writeVersionToPath(FileSystem fs, Path path, int versionToWrite) throws IOException {
    try (FSDataOutputStream out = fs.create(path, false /* overwrite */)) {
      out.write(String.valueOf(versionToWrite).getBytes(StandardCharsets.UTF_8));
    }
  }

  @VisibleForTesting
  int findVersion() {
    Path versionHintFile = versionHintFile();
    FileSystem fs = getFileSystem(versionHintFile, conf);

    try (InputStreamReader fsr =
            new InputStreamReader(fs.open(versionHintFile), StandardCharsets.UTF_8);
        BufferedReader in = new BufferedReader(fsr)) {
      return Integer.parseInt(in.readLine().replace("\n", ""));

View on GitHub (pinned to 86d9c8fc54)