apache/iceberg · error

Unknown table: . Table not found in catalog.

Error message

Unknown table: %s. Table not found in catalog.

What it means

SparkTableUtil.getPartitions wraps Spark catalog's NoSuchTableException into an unchecked Iceberg exception. It is thrown when the table identifier itself (database exists, table missing, or both unresolvable) cannot be found while listing partitions. SparkTableUtil rethrows because partition listing requires a live catalog table.

Solutions

  1. Check table existence first with spark.catalog().tableExists(db, table) and correct the TableIdentifier.
  2. Qualify the identifier with the correct database/catalog (catalog.db.table) instead of relying on the current database.
  3. Catch the unchecked exception whose cause is NoSuchTableException and treat it as user-input validation failure.

Example fix

// before
SparkTableUtil.getPartitions(spark, new TableIdentifier("orders", Some.apply("sales")), null);
// after
if (!spark.catalog().tableExists("sales", "orders")) { throw new IllegalArgumentException("sales.orders not found"); }
SparkTableUtil.getPartitions(spark, new TableIdentifier("orders", Some.apply("sales")), null);
Defensive patterns

Strategy: validation

Validate before calling

TableIdentifier ident = ...;
if (!spark.catalog().tableExists(ident.database().get(), ident.table())) {
  throw new IllegalArgumentException("Table not found: " + ident);
}

Try / catch

try { SparkTableUtil.getPartitions(spark, ident, null); } catch (RuntimeException e) { if (e.getCause() instanceof NoSuchTableException) { /* handle missing table */ } else throw e; }

Prevention

When it happens

Trigger: Calling SparkTableUtil.getPartitions(sparkSession, tableIdent, partitionFilter) where catalog.listPartitions throws NoSuchTableException because the TableIdentifier does not resolve to an existing Spark table.

Common situations: Table name typo; table dropped or renamed before the import; pointing at an Iceberg table already migrated (it no longer exists in the session catalog as a Spark table); case-sensitivity issues with spark.sql.caseSensitive.

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/9edcf4a7e4e63ce8. Report an issue: GitHub.

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkTableUtil.java:160

      Option<scala.collection.immutable.Map<String, String>> scalaPartitionFilter;
      if (partitionFilter != null && !partitionFilter.isEmpty()) {
        Builder<Tuple2<String, String>, scala.collection.immutable.Map<String, String>> builder =
            Map$.MODULE$.newBuilder();
        partitionFilter.forEach((key, value) -> builder.$plus$eq(Tuple2.apply(key, value)));
        scalaPartitionFilter = Option.apply(builder.result());
      } else {
        scalaPartitionFilter = Option.empty();
      }
      Seq<CatalogTablePartition> partitions =
          catalog.listPartitions(tableIdent, scalaPartitionFilter).toIndexedSeq();
      return JavaConverters.seqAsJavaListConverter(partitions).asJava().stream()
          .map(catalogPartition -> toSparkPartition(catalogPartition, catalogTable))
          .collect(Collectors.toList());
    } catch (NoSuchDatabaseException e) {
      throw SparkExceptionUtil.toUncheckedException(
          e, "Unknown table: %s. Database not found in catalog.", tableIdent);
    } catch (NoSuchTableException e) {
      throw SparkExceptionUtil.toUncheckedException(
          e, "Unknown table: %s. Table not found in catalog.", tableIdent);
    }
  }

  private static List<DataFile> listPartition(
      SparkPartition partition,
      PartitionSpec spec,
      SerializableConfiguration conf,
      MetricsConfig metricsConfig,
      NameMapping mapping,
      boolean ignoreMissingFiles,
      ExecutorService service) {
    try {
      return TableMigrationUtil.listPartition(
          partition.values,
          partition.uri,
          partition.format,
          spec,

View on GitHub (pinned to 86d9c8fc54)