apache/iceberg · error · RuntimeIOException

Failed to refresh the table

Error message

Failed to refresh the table

What it means

refresh() wraps IO errors encountered while reading version hint or metadata files into RuntimeIOException with this message. The underlying IOException (access problem, FS outage) is the cause. It signals the refresh could not read table metadata from the filesystem.

Solutions

1. Check the cause chain for the underlying IOException and fix FS connectivity/permissions
2. Retry after confirming the filesystem is reachable (hdfs dfs -ls on the metadata path)
3. Refresh Kerberos tokens / credentials if auth expired
4. Validate the storage endpoint configuration (fs.defaultFS, S3 endpoint) is correct

Example fix

// before: table ref held across a long job, refresh hits HDFS outage
Table table = catalog.loadTable(...); // used hours later
// after: reload/retry around refresh
try {
  table.refresh();
} catch (RuntimeIOException e) {
  table = catalog.loadTable(identifier); // reconnect and retry
}

if (!fs.exists(new Path(root, "metadata/version-hint.text"))) throw new SkipRefreshException();

try { table.refresh(); } catch (RuntimeIOException e) { LOG.warn("refresh failed", e.getCause()); /* reconnect / retry with backoff */ }

When it happens

Trigger: IOException while reading version-hint.text or the version metadata file during refresh(): HDFS NameNode unavailable, permission denied on metadata files, network partition to HDFS/S3, corrupted file causing read failure.

Common situations: HDFS cluster restarted or in safe mode; Kerberos credentials expired; S3 endpoint misconfigured; transient network failure in a long-running Spark job reading a table.

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

• Failed to delete file
• Failed to delete file
• Failed to get file system for path
• Failed to get status for file
• Failed to list namespace under

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

Appendix: source

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

        return null;
      } else if (metadataFile == null) {
        throw new ValidationException(
            "Metadata file for version %d is missing under %s", ver, metadataRoot());
      }

      Path nextMetadataFile = getMetadataFile(ver + 1);
      while (nextMetadataFile != null) {
        ver += 1;
        metadataFile = nextMetadataFile;
        nextMetadataFile = getMetadataFile(ver + 1);
      }

      updateVersionAndMetadata(ver, metadataFile.toString());

      this.shouldRefresh = false;
      return currentMetadata;
    } catch (IOException e) {
      throw new RuntimeIOException(e, "Failed to refresh the table");
    }
  }

  @Override
  public void commit(TableMetadata base, TableMetadata metadata) {
    Pair<Integer, TableMetadata> current = versionAndMetadata();
    if (base != current.second()) {
      throw new CommitFailedException("Cannot commit changes based on stale table metadata");
    }

    if (base == metadata) {
      LOG.info("Nothing to commit.");
      return;
    }

    Preconditions.checkArgument(
        base == null || base.location().equals(metadata.location()),
        "Hadoop path-based tables cannot be relocated");

View on GitHub (pinned to 86d9c8fc54)