apache/iceberg · error · NoSuchTableException

NoSuchTableException(ident)

Error message

NoSuchTableException(ident)

What it means

Spark's alterTable was called with an identifier, but the underlying Iceberg catalog could not load a table with that name, so org.apache.iceberg.exceptions.NoSuchTableException was caught and rethrown as Spark's NoSuchTableException. This means the table does not exist (or is not visible) in the configured catalog. Spark rethrows it so callers see the catalog plugin's checked exception type.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:367

        } else {
          propertyChanges.add(set);
        }
      } else if (change instanceof RemoveProperty) {
        propertyChanges.add(change);
      } else if (change instanceof ColumnChange) {
        schemaChanges.add(change);
      } else {
        throw new UnsupportedOperationException("Cannot apply unknown table change: " + change);
      }
    }

    try {
      org.apache.iceberg.Table table = icebergCatalog.loadTable(buildIdentifier(ident));
      commitChanges(
          table, setLocation, setSnapshotId, pickSnapshotId, propertyChanges, schemaChanges);
      return new SparkTable(table, true /* refreshEagerly */);
    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {
      throw new NoSuchTableException(ident);
    }
  }

  @Override
  public boolean dropTable(Identifier ident) {
    return catalogDropTable(ident);
  }

  @Override
  public boolean purgeTable(Identifier ident) {
    try {
      org.apache.iceberg.Table table = icebergCatalog.loadTable(buildIdentifier(ident));
      ValidationException.check(
          PropertyUtil.propertyAsBoolean(table.properties(), GC_ENABLED, GC_ENABLED_DEFAULT),
          "Cannot purge table: GC is disabled (deleting files may corrupt other tables)");
      String metadataFileLocation =
          ((HasTableOperations) table).operations().current().metadataFileLocation();

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Verify the exact table exists with SELECT or SHOW TABLES IN <catalog>.<namespace> using the same catalog and namespace as the ALTER statement.
  2. Check the fully-qualified identifier: ensure session catalog (spark_catalog) vs named Iceberg catalog configuration matches how the table was created.
  3. Confirm no concurrent job dropped the table; inspect catalog/Hive metastore contents directly.
  4. If the table exists but loadTable fails, check the catalog's warehouse/FileIO configuration (permissions, endpoint) in the Spark conf.

Example fix

// before
spark.sql("ALTER TABLE mydb.orders SET TBLPROPERTIES ('note'='x')") // NoSuchTableException

// after
if (!spark.catalog().tableExists("iceberg_catalog.mydb.orders")) {
  throw new IllegalStateException("Table missing - check catalog name");
}
spark.sql("ALTER TABLE iceberg_catalog.mydb.orders SET TBLPROPERTIES ('note'='x')")
Defensive patterns

Strategy: try-catch

Validate before calling

if (!spark.catalog().tableExists("iceberg_catalog.mydb.orders")) {
  throw new IllegalStateException("Table does not exist before ALTER");
}

Try / catch

try {
  spark.sql("ALTER TABLE iceberg_catalog.mydb.orders SET TBLPROPERTIES (...)");
} catch (NoSuchTableException e) {
  // table absent or unloaded: log identifier from e, create or re-register it
}

Prevention

When it happens

Trigger: Calling ALTER TABLE on a table resolved through an Iceberg Spark catalog whose loadTable(ident) fails; the table was dropped by another process between resolution and ALTER; wrong catalog/namespace qualifier in the identifier; or a case-sensitivity mismatch between Spark's identifier and the Iceberg catalog's stored name.

Common situations: Running ALTER TABLE ... SET TBLPROPERTIES against a table created under a different catalog (e.g. spark_catalog vs a custom HadoopCatalog); typos in three-part table names; HDFS/S3 outages making manifest lookups fail and surface as NoSuchTable; multi-tenant setups where another job dropped the table mid-flight.

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/2e3b4b32bad9f4a9. Report an issue: GitHub.