apache/iceberg · error · RuntimeIOException

Failed to list namespace under: %s

Error message

Failed to list namespace under: %s

What it means

HadoopCatalog.listNamespaces wraps IOExceptions from fs.listStatusIterator(nsPath) into a RuntimeIOException. The namespace exists, but enumerating its child entries failed at the I/O level. The cause IOException is preserved.

Source

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

            : new Path(warehouseLocation, SLASH.join(namespace.levels()));
    if (!isNamespace(nsPath)) {
      throw new NoSuchNamespaceException("Namespace does not exist: %s", namespace);
    }

    try {
      // using the iterator listing allows for paged downloads
      // from HDFS and prefetching from object storage.
      List<Namespace> namespaces = Lists.newArrayList();
      RemoteIterator<FileStatus> it = fs.listStatusIterator(nsPath);
      while (it.hasNext()) {
        Path path = it.next().getPath();
        if (isNamespace(path)) {
          namespaces.add(append(namespace, path.getName()));
        }
      }
      return namespaces;
    } catch (IOException ioe) {
      throw new RuntimeIOException(ioe, "Failed to list namespace under: %s", namespace);
    }
  }

  private Namespace append(Namespace ns, String name) {
    String[] levels = Arrays.copyOfRange(ns.levels(), 0, ns.levels().length + 1);
    levels[ns.levels().length] = name;
    return Namespace.of(levels);
  }

  @Override
  public boolean dropNamespace(Namespace namespace) {
    Path nsPath = new Path(warehouseLocation, SLASH.join(namespace.levels()));

    if (!isNamespace(nsPath) || namespace.isEmpty()) {
      return false;
    }

    try {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the wrapped IOException cause (throttling vs connectivity vs auth).
2. Retry with backoff for transient cloud/HDFS errors.
3. Verify credentials and filesystem configuration used to build the HadoopCatalog.
4. For S3/ADLS, reduce listing pressure or use prefix-appropriate warehouse layouts.
5. Confirm the namespace directory is accessible (permissions) to the current user.

Example fix

// before
List<Namespace> children = catalog.listNamespaces(ns);

// after
try {
  List<Namespace> children = catalog.listNamespaces(ns);
} catch (RuntimeIOException e) {
  LOG.warn("Listing failed, retrying after backoff", e);
  // retry with backoff
}

if (!catalog.namespaceExists(ns)) { return List.of(); }

try { catalog.listNamespaces(ns); } catch (RuntimeIOException e) { Tasks.foreach(ns).retry(3).exponentialBackoff(100, 10000).run(n -> catalog.listNamespaces(n)); }

When it happens

Trigger: Calling catalog.listNamespaces(namespace) when the directory listing throws: HDFS NameNode unreachable, object-store throttling/network failure, credentials expired during the listing, or transient RemoteIterator errors.

Common situations: Cloud storage rate limits during large listings, HDFS cluster maintenance, network partitions, expired STS tokens mid-operation, or misconfigured filesystem credentials in the catalog's Hadoop conf.

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 tables under: %s
• Failed to delete file: %s
• Create namespace failed: %s
• Namespace delete failed: %s
• Failed to delete file: %s

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