apache/iceberg · warning

Error trying to recover the latest version number for

Error message

Error trying to recover the latest version number for {}

What it means

After failing to read version-hint.text, findVersion() falls back to listing the metadata directory to recover the max version. If that recovery listing itself throws IOException, this warning is logged and 0 is returned, meaning the table will be treated as having no version. This indicates the metadata directory could not be scanned at all.

Solutions

1. Fix read permissions on the table metadata directory
2. Verify the metadata directory exists and contains vN.metadata.json files
3. Retry after resolving transient storage/cloud storage errors
4. Check filesystem client logs for the underlying IOException root cause
5. Re-sync the table location from a healthy copy

Example fix

// before
hdfs dfs -ls /warehouse/db/table/metadata  # -> Permission denied
// after
hdfs dfs -chmod -R o+r /warehouse/db/table/metadata

// before loading the table
FileSystem fs = metadataRoot.getFileSystem(conf);
if (!fs.exists(metadataRoot) || fs.listStatus(metadataRoot).length == 0) {
  throw new IllegalStateException("metadata dir unreadable/empty");
}

try {
  table = catalog.loadTable(name);
} catch (RuntimeException e) {
  // check HDFS/cloud storage health, fix permissions, retry once
}

When it happens

Trigger: findVersion() called when version-hint.text read failed AND the recovery FileSystem.listStatus(metadataRoot()) (or per-file version parsing) throws IOException — e.g. metadata directory missing read permission or transient FS outage.

Common situations: HDFS/S3 permission misconfiguration on the metadata directory; transient cloud storage throttling or 5xx during listing; metadata root deleted while a table handle is still open.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Error reading version hint file
• Failed to update version hint
• 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/8c787cdb77a574f2. Report an issue: GitHub.

Appendix: source

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

        }

        // List the metadata directory to find the version files, and try to recover the max
        // available version
        FileStatus[] files =
            fs.listStatus(
                metadataRoot(), name -> VERSION_PATTERN.matcher(name.getName()).matches());
        int maxVersion = 0;

        for (FileStatus file : files) {
          int currentVersion = version(file.getPath().getName());
          if (currentVersion > maxVersion && getMetadataFile(currentVersion) != null) {
            maxVersion = currentVersion;
          }
        }

        return maxVersion;
      } catch (IOException io) {
        LOG.warn("Error trying to recover the latest version number for {}", versionHintFile, io);
        return 0;
      }
    }
  }

  /**
   * Renames the source file to destination, using the provided file system. If the rename failed,
   * an attempt will be made to delete the source file.
   *
   * @param fs the filesystem used for the rename
   * @param src the source file
   * @param dst the destination file
   */
  private void renameToFinal(FileSystem fs, Path src, Path dst, int nextVersion) {
    try {
      if (!lockManager.acquire(dst.toString(), src.toString())) {
        throw new CommitFailedException(
            "Failed to acquire lock on file: %s with owner: %s", dst, src);

View on GitHub (pinned to 86d9c8fc54)