apache/iceberg · error · RuntimeIOException

Failed to list tables under: %s

Error message

Failed to list tables under: %s

What it means

HadoopCatalog.listTables wraps IOExceptions from the underlying FileSystem directory listing into a RuntimeIOException. It means the directory-iteration over the namespace's warehouse path failed (I/O-level, not a missing namespace, which throws NoSuchNamespaceException instead). The original IOException is preserved as the cause.

Source

Thrown at core/src/main/java/org/apache/iceberg/hadoop/HadoopCatalog.java:217

      if (!isDirectory(nsPath)) {
        throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
      }
      RemoteIterator<FileStatus> it = fs.listStatusIterator(nsPath);
      while (it.hasNext()) {
        FileStatus status = it.next();
        if (!status.isDirectory()) {
          // Ignore the path which is not a directory.
          continue;
        }

        Path path = status.getPath();
        if (isTableDir(path)) {
          TableIdentifier tblIdent = TableIdentifier.of(namespace, path.getName());
          tblIdents.add(tblIdent);
        }
      }
    } catch (IOException ioe) {
      throw new RuntimeIOException(ioe, "Failed to list tables under: %s", namespace);
    }

    return Lists.newArrayList(tblIdents);
  }

  @Override
  protected boolean isValidIdentifier(TableIdentifier identifier) {
    return true;
  }

  @Override
  protected TableOperations newTableOps(TableIdentifier identifier) {
    return new HadoopTableOperations(
        new Path(defaultWarehouseLocation(identifier)), fileIO, conf, lockManager);
  }

  @Override
  protected String defaultWarehouseLocation(TableIdentifier tableIdentifier) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check the underlying IOException cause to see if it is connectivity, permissions, or a bad path.
2. Verify the warehouse location URI scheme and host are reachable (e.g. hdfs://nn:8020 or s3a://bucket) from this client.
3. Validate Hadoop/FileSystem configuration (core-site.xml, hdfs-site.xml, cloud credential providers) in the Configuration given to HadoopCatalog.
4. Retry on transient errors; for cloud stores verify credentials haven't expired.
5. Confirm the namespace directory exists via listNamespaces before listing tables.

Example fix

// before: listing with unverified cluster
List<TableIdentifier> tables = catalog.listTables(Namespace.of("db"));

// after: pre-check namespace and catch I/O failure
try {
  if (!catalog.namespaceExists(Namespace.of("db"))) {
    throw new IllegalStateException("Namespace db missing");
  }
  List<TableIdentifier> tables = catalog.listTables(Namespace.of("db"));
} catch (RuntimeIOException e) {
  LOG.error("Filesystem listing failed; check warehouse URI and connectivity", e);
}

if (!catalog.namespaceExists(namespace)) { throw new IllegalArgumentException("Namespace missing: " + namespace); }

try { catalog.listTables(ns); } catch (RuntimeIOException e) { // inspect e.getCause() IOException; retry or fail with context }

When it happens

Trigger: Calling catalog.listTables(namespace) when fs.listStatusIterator(nsPath) throws IOException: HDFS NameNode unreachable, S3/ADLS object-store list failure, credentials expired mid-listing, or a transient network error while iterating the RemoteIterator.

Common situations: Misconfigured warehouse location (wrong filesystem scheme, e.g. missing hdfs:// namenode host), HDFS cluster down or in safe mode, expired cloud credentials (S3/ADLS/GCS), network partitions, or wrong core-site/fs config in the Hadoop conf passed to the catalog.

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 list namespace under: %s
• Namespace delete failed: %s
• Failed to delete file: %s
• Failed to delete file: %s
• Failed to get status for file: %s

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