apache/iceberg · error · NoSuchTableException

org.apache.iceberg.exceptions.NoSuchTableException:

Error message

org.apache.iceberg.exceptions.NoSuchTableException:

What it means

SparkCatalog.loadTable wraps org.apache.iceberg.exceptions.NoSuchTableException from Catalog.loadTable into Spark's NoSuchTableException carrying the identifier. The underlying Iceberg catalog could not resolve the identifier to a table.

Source

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

    return CatalogUtil.buildIcebergCatalog(name, optionsMap, conf);
  }

  /**
   * Build an Iceberg {@link TableIdentifier} for the given Spark identifier.
   *
   * @param identifier Spark's identifier
   * @return an Iceberg identifier
   */
  protected TableIdentifier buildIdentifier(Identifier identifier) {
    return Spark3Util.identifierToTableIdentifier(identifier);
  }

  @Override
  public Table loadTable(Identifier ident) throws NoSuchTableException {
    try {
      return load(ident);
    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {
      throw new NoSuchTableException(ident);
    }
  }

  @Override
  public Table loadTable(Identifier ident, String version) throws NoSuchTableException {
    Table table = loadTable(ident);

    if (table instanceof SparkTable) {
      SparkTable sparkTable = (SparkTable) table;

      Preconditions.checkArgument(
          sparkTable.snapshotId() == null && sparkTable.branch() == null,
          "Cannot do time-travel based on both table identifier and AS OF");

      try {
        return sparkTable.copyWithSnapshotId(Long.parseLong(version));
      } catch (NumberFormatException e) {
        SnapshotRef ref = sparkTable.table().refs().get(version);

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Verify the table exists: SHOW TABLES IN <catalog>.<namespace> and check exact identifier casing
  2. Check catalog configuration (warehouse, URI) points at the environment that actually contains the table
  3. Refresh the Spark session/catalog if the table was recently created or recreated by another process
  4. Catch Spark's NoSuchTableException (org.apache.spark.sql.catalyst.NoSuchTableException) around loadTable in programmatic use

Example fix

// before
Table t = sparkCatalog.loadTable(Identifier.of(new String[]{"db"}, "tabl"));
// after
Identifier ident = Identifier.of(new String[]{"db"}, "table");
if (catalogOps.tableExists(ident)) {
  Table t = sparkCatalog.loadTable(ident);
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (!catalog.tableExists(ident)) {
  throw new IllegalStateException("Table " + ident + " does not exist in " + catalogName);
}

Try / catch

try { table = sparkCatalog.loadTable(ident); } catch (NoSuchTableException e) { /* check identifier spelling/casing and catalog config */ }

Prevention

When it happens

Trigger: Calling loadTable with a misspelled or non-existent table/namespace, a table dropped by another process, or a catalog pointed at the wrong warehouse/location.

Common situations: Typo in table name; stale Spark session after the table was dropped/recreated elsewhere; wrong warehouse path or catalog options so the metadata file is not found; case/namespace mismatches.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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