apache/iceberg · error

Unknown table: . Database not found in catalog.

Error message

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

What it means

SparkTableUtil.getPartitions wraps Spark catalog's NoSuchDatabaseException into an unchecked Iceberg exception while listing partitions of a Spark table. The message text reuses the 'Unknown table' phrasing, but it is thrown when the DATABASE (namespace) of the given table identifier does not exist in the Spark session catalog. SparkTableUtil throws it because listPartitions cannot proceed without a resolvable parent database.

Solutions

  1. Verify the database exists: spark.sessionState.catalog().databaseExists(db) or SHOW DATABASES, and correct the identifier (use catalog.db.table fully qualified).
  2. Ensure the Spark session is configured with the right catalog/metastore (spark.sql.catalog.* and hive metastore URIs) where the database actually exists.
  3. Catch the resulting unchecked exception (NoSuchDatabaseException cause) and handle missing-DB as a controlled failure path.

Example fix

// before
List<SparkPartition> parts = SparkTableUtil.getPartitions(spark, new org.apache.spark.sql.catalyst.TableIdentifier("tbl", Some.apply("wrong_db")), null);
// after
if (!spark.catalog().databaseExists("wrong_db")) { throw new IllegalArgumentException("database wrong_db does not exist"); }
List<SparkPartition> parts = SparkTableUtil.getPartitions(spark, new org.apache.spark.sql.catalyst.TableIdentifier("tbl", Some.apply("right_db")), null);
Defensive patterns

Strategy: validation

Validate before calling

TableIdentifier ident = ...;
if (!spark.catalog().databaseExists(ident.database().get())) {
  throw new IllegalArgumentException("Database not found: " + ident.database().get());
}

Try / catch

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

Prevention

When it happens

Trigger: Calling SparkTableUtil.getPartitions(sparkSession, tableIdent, partitionFilter) with a TableIdentifier whose database does not exist in the Spark catalog (e.g. catalog.listPartitions throws NoSuchDatabaseException).

Common situations: Typos in the database name; running against a different Spark session/catalog (e.g. session catalog vs Hive metastore) than the one where the table lives; database dropped by another job before import; missing catalog qualifier in the identifier so it resolves against the wrong catalog.

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/112d8e58f0265194. Report an issue: GitHub.

Appendix: source

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

      SessionCatalog catalog = spark.sessionState().catalog();
      CatalogTable catalogTable = catalog.getTableMetadata(tableIdent);

      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,

View on GitHub (pinned to 86d9c8fc54)