{"record":{"id":"25eea56fe5e5129d","repo":"apache/iceberg","slug":"failed-to-list-namespace-under-s","errorCode":null,"errorMessage":"Failed to list namespace under: %s","messagePattern":"Failed to list namespace under: (.+?)","errorType":"exception","errorClass":"RuntimeIOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/hadoop/HadoopCatalog.java","lineNumber":325,"sourceCode":"            : new Path(warehouseLocation, SLASH.join(namespace.levels()));\n    if (!isNamespace(nsPath)) {\n      throw new NoSuchNamespaceException(\"Namespace does not exist: %s\", namespace);\n    }\n\n    try {\n      // using the iterator listing allows for paged downloads\n      // from HDFS and prefetching from object storage.\n      List<Namespace> namespaces = Lists.newArrayList();\n      RemoteIterator<FileStatus> it = fs.listStatusIterator(nsPath);\n      while (it.hasNext()) {\n        Path path = it.next().getPath();\n        if (isNamespace(path)) {\n          namespaces.add(append(namespace, path.getName()));\n        }\n      }\n      return namespaces;\n    } catch (IOException ioe) {\n      throw new RuntimeIOException(ioe, \"Failed to list namespace under: %s\", namespace);\n    }\n  }\n\n  private Namespace append(Namespace ns, String name) {\n    String[] levels = Arrays.copyOfRange(ns.levels(), 0, ns.levels().length + 1);\n    levels[ns.levels().length] = name;\n    return Namespace.of(levels);\n  }\n\n  @Override\n  public boolean dropNamespace(Namespace namespace) {\n    Path nsPath = new Path(warehouseLocation, SLASH.join(namespace.levels()));\n\n    if (!isNamespace(nsPath) || namespace.isEmpty()) {\n      return false;\n    }\n\n    try {","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/hadoop/HadoopCatalog.java#L307-L343","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped IOException cause (throttling vs connectivity vs auth).","Retry with backoff for transient cloud/HDFS errors.","Verify credentials and filesystem configuration used to build the HadoopCatalog.","For S3/ADLS, reduce listing pressure or use prefix-appropriate warehouse layouts.","Confirm the namespace directory is accessible (permissions) to the current user."],"exampleFix":"// before\nList<Namespace> children = catalog.listNamespaces(ns);\n\n// after\ntry {\n  List<Namespace> children = catalog.listNamespaces(ns);\n} catch (RuntimeIOException e) {\n  LOG.warn(\"Listing failed, retrying after backoff\", e);\n  // retry with backoff\n}","handlingStrategy":"retry","validationCode":"if (!catalog.namespaceExists(ns)) { return List.of(); }","typeGuard":null,"tryCatchPattern":"try { catalog.listNamespaces(ns); } catch (RuntimeIOException e) { Tasks.foreach(ns).retry(3).exponentialBackoff(100, 10000).run(n -> catalog.listNamespaces(n)); }","preventionTips":["Apply backoff on cloud-store listings","Keep STS/credential lifetimes longer than job duration","Check filesystem conf before long-running jobs"],"tags":["io","filesystem","listing","namespace","hadoop"],"backgroundTag":"file-read-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}