apache/iceberg · error · NoSuchNamespaceException

Cannot create table %s as the namespace does not exist

Error message

Cannot create table %s as the namespace does not exist

What it means

stageDestTable calls destCatalog().stageCreate; if Spark reports NoSuchNamespaceException, the action rethrows it as Iceberg NoSuchNamespaceException stating the destination namespace does not exist. The destination catalog must already contain the target namespace.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/actions/BaseTableCreationSparkAction.java:164

            + "Catalog '%s' was of class '%s' but '%s' or '%s' are required",
        catalog.name(),
        catalog.getClass().getName(),
        SparkSessionCatalog.class.getName(),
        SparkCatalog.class.getName());

    return (StagingTableCatalog) catalog;
  }

  protected StagedSparkTable stageDestTable() {
    try {
      Map<String, String> props = destTableProps();
      return (StagedSparkTable)
          destCatalog()
              .stageCreate(
                  destTableIdent(),
                  Spark3Util.tableInfo(sourceTable.columns(), sourceTable.partitioning(), props));
    } catch (org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException e) {
      throw new NoSuchNamespaceException(
          "Cannot create table %s as the namespace does not exist", destTableIdent());
    } catch (org.apache.spark.sql.catalyst.analysis.TableAlreadyExistsException e) {
      throw new AlreadyExistsException(
          "Cannot create table %s as it already exists", destTableIdent());
    }
  }

  protected void ensureNameMappingPresent(Table table) {
    if (!table.properties().containsKey(TableProperties.DEFAULT_NAME_MAPPING)) {
      NameMapping nameMapping = MappingUtil.create(table.schema());
      String nameMappingJson = NameMappingParser.toJson(nameMapping);
      table.updateProperties().set(TableProperties.DEFAULT_NAME_MAPPING, nameMappingJson).commit();
    }
  }

  protected String getMetadataLocation(Table table) {
    String defaultValue =
        LocationUtil.stripTrailingSlash(table.location()) + "/" + ICEBERG_METADATA_FOLDER;

View on GitHub (pinned to 86d9c8fc54)

Solutions

Create the destination namespace first: CREATE NAMESPACE catalog.ns
Verify the destination identifier and catalog name are correct
List namespaces (SHOW NAMESPACES IN catalog) to confirm the target exists

Example fix

// before
CALL cat.system.snapshot('src.tbl', 'cat.analytics.orders') // analytics missing
// after
CREATE NAMESPACE cat.analytics;
CALL cat.system.snapshot('src.tbl', 'cat.analytics.orders');

Defensive patterns

Strategy: validation

Validate before calling

if (!spark.catalog().databaseExists(ns)) { spark.sql("CREATE NAMESPACE " + ns); }

Type guard

boolean namespaceExists(SparkSession spark, String ns) { return spark.catalog().databaseExists(ns); }

Try / catch

try { callAction(...); } catch (NoSuchNamespaceException e) { LOG.error("Dest namespace missing for {}", destIdent, e); throw e; }

Prevention

CREATE NAMESPACE before create-like actions
Verify destination identifiers against SHOW NAMESPACES output
Automate namespace provisioning in job setup

When it happens

Trigger: CREATE/SNAPSHOT/ MIGRATE actions with a destination identifier in a namespace never created in the destination catalog — e.g. snapshotting into db2.backup when namespace db2.backup is absent.

Common situations: Typos in destination namespace; forgetting CREATE NAMESPACE before the action; pointing the destination at a catalog where the namespace hierarchy differs.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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