apache/iceberg · error · org.apache.spark.sql.catalyst.analysis.NoSuchTableException

NoSuchTableException

Error message

NoSuchTableException: <ident>

What it means

stageReplace (backing REPLACE TABLE / staged replace transactions) requires the target table to already exist. If the Iceberg catalog reports NoSuchTableException, Spark translates it into Spark's NoSuchTableException with the identifier.

Solutions

1. Verify the table exists (SHOW TABLES IN catalog.db) and correct the identifier.
2. Use CREATE TABLE if the table genuinely should be created new.
3. Fully qualify catalog.namespace.table to ensure resolution against the intended catalog.
4. Catch NoSuchTableException and branch to create-vs-replace logic.

Example fix

-- before
REPLACE TABLE catalog.db.t AS SELECT ...; -- throws if t missing
-- after
CREATE TABLE IF NOT EXISTS catalog.db.t AS SELECT ...;

-- Spark SQL precheck
SHOW TABLES IN catalog.db LIKE 't';

try {
  spark.sql("REPLACE TABLE catalog.db.t AS SELECT ...");
} catch (NoSuchTableException e) {
  spark.sql("CREATE TABLE IF NOT EXISTS catalog.db.t AS SELECT ...");
}

When it happens

Trigger: Executing REPLACE TABLE or CREATE OR REPLACE via the staged-replace path when the identifier does not exist in the catalog; typo in table name or wrong namespace/catalog qualification.

Common situations: REPLACE TABLE run against a name that was dropped concurrently; misspelled table names; using a different default catalog than where the table lives.

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

• Cannot add column since setting default values in Spark is…
• Cannot find source table
• Cannot specify the 'identifier-fields' because it's a…
• Cannot specify the 'sort-order' because it's a reserved…
• does not support altering tables

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

Appendix: source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:257

    }
  }

  @Override
  public StagedTable stageReplace(
      Identifier ident, StructType schema, Transform[] transforms, Map<String, String> properties)
      throws NoSuchTableException {
    Schema icebergSchema = SparkSchemaUtil.convert(schema);
    try {
      Catalog.TableBuilder builder = newBuilder(ident, icebergSchema);
      Transaction transaction =
          builder
              .withPartitionSpec(Spark3Util.toPartitionSpec(icebergSchema, transforms))
              .withLocation(properties.get("location"))
              .withProperties(Spark3Util.rebuildCreateProperties(properties))
              .replaceTransaction();
      return new StagedSparkTable(transaction);
    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {
      throw new NoSuchTableException(ident);
    }
  }

  @Override
  public StagedTable stageCreateOrReplace(
      Identifier ident, StructType schema, Transform[] transforms, Map<String, String> properties) {
    Schema icebergSchema = SparkSchemaUtil.convert(schema);
    Catalog.TableBuilder builder = newBuilder(ident, icebergSchema);
    Transaction transaction =
        builder
            .withPartitionSpec(Spark3Util.toPartitionSpec(icebergSchema, transforms))
            .withLocation(properties.get("location"))
            .withProperties(Spark3Util.rebuildCreateProperties(properties))
            .createOrReplaceTransaction();
    return new StagedSparkTable(transaction);
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)