apache/iceberg · error · RuntimeIOException

Create namespace failed: %s

Error message

Create namespace failed: %s

What it means

HadoopCatalog.createNamespace wraps IOExceptions from fs.mkdirs(nsPath) into a RuntimeIOException. The namespace existence check passed, but creating the directory on the filesystem failed at the I/O level (permissions, connectivity, storage errors).

Source

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

  public void createNamespace(Namespace namespace, Map<String, String> meta) {
    Preconditions.checkArgument(
        !namespace.isEmpty(), "Cannot create namespace with invalid name: %s", namespace);
    if (!meta.isEmpty()) {
      throw new UnsupportedOperationException(
          "Cannot create namespace " + namespace + ": metadata is not supported");
    }

    Path nsPath = new Path(warehouseLocation, SLASH.join(namespace.levels()));

    if (isNamespace(nsPath)) {
      throw new AlreadyExistsException("Namespace already exists: %s", namespace);
    }

    try {
      fs.mkdirs(nsPath);

    } catch (IOException e) {
      throw new RuntimeIOException(e, "Create namespace failed: %s", namespace);
    }
  }

  @Override
  public List<Namespace> listNamespaces(Namespace namespace) {
    Path nsPath =
        namespace.isEmpty()
            ? new Path(warehouseLocation)
            : 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);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check the IOException cause for permission vs connectivity vs quota errors.
2. Verify the process user has write permission on the warehouse parent directory (HDFS ACLs/permissions, IAM policies for cloud stores).
3. Check HDFS quota (hdfs dfs -count -q) or cloud bucket policies/limits.
4. Retry on transient network/cloud errors.
5. Verify Kerberos/authentication is valid for the Hadoop FileSystem.

Example fix

// before
catalog.createNamespace(ns, Collections.emptyMap());

// after: catch and diagnose
try {
  catalog.createNamespace(ns, Collections.emptyMap());
} catch (RuntimeIOException e) {
  LOG.error("mkdirs failed for {} - check warehouse write permissions", ns, e);
  throw e;
}

// Pre-check write access on warehouse parent if possible; otherwise ensure creds/permissions up front

try { catalog.createNamespace(ns, Collections.emptyMap()); } catch (RuntimeIOException e) { // inspect e.getCause(): permission vs connectivity vs quota }

When it happens

Trigger: Calling catalog.createNamespace(namespace, meta) when fs.mkdirs throws IOException: no write permission on the parent warehouse directory, HDFS unavailable/quota exceeded, cloud-store credential or network failure.

Common situations: Warehouse directory owned by another user/service account, HDFS disk quota exhausted, transient S3/GCS/ADLS outages, Kerberos ticket expiry, or a read-only filesystem mount.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Failed to list namespace under: %s
• Failed to list tables under: %s
• Failed to delete file: %s
• Namespace delete failed: %s
• Cannot set namespace properties " + namespace + " : setPrope

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