{"record":{"id":"112d8e58f0265194","repo":"apache/iceberg","slug":"unknown-table-s-database-not-found-in-catalog-112d8e","errorCode":null,"errorMessage":"Unknown table: %s. Database not found in catalog.","messagePattern":"Unknown table: (.+?)\\. Database not found in catalog\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkTableUtil.java","lineNumber":157,"sourceCode":"      SessionCatalog catalog = spark.sessionState().catalog();\n      CatalogTable catalogTable = catalog.getTableMetadata(tableIdent);\n\n      Option<scala.collection.immutable.Map<String, String>> scalaPartitionFilter;\n      if (partitionFilter != null && !partitionFilter.isEmpty()) {\n        Builder<Tuple2<String, String>, scala.collection.immutable.Map<String, String>> builder =\n            Map$.MODULE$.newBuilder();\n        partitionFilter.forEach((key, value) -> builder.$plus$eq(Tuple2.apply(key, value)));\n        scalaPartitionFilter = Option.apply(builder.result());\n      } else {\n        scalaPartitionFilter = Option.empty();\n      }\n      Seq<CatalogTablePartition> partitions =\n          catalog.listPartitions(tableIdent, scalaPartitionFilter).toIndexedSeq();\n      return JavaConverters.seqAsJavaListConverter(partitions).asJava().stream()\n          .map(catalogPartition -> toSparkPartition(catalogPartition, catalogTable))\n          .collect(Collectors.toList());\n    } catch (NoSuchDatabaseException e) {\n      throw SparkExceptionUtil.toUncheckedException(\n          e, \"Unknown table: %s. Database not found in catalog.\", tableIdent);\n    } catch (NoSuchTableException e) {\n      throw SparkExceptionUtil.toUncheckedException(\n          e, \"Unknown table: %s. Table not found in catalog.\", tableIdent);\n    }\n  }\n\n  private static List<DataFile> listPartition(\n      SparkPartition partition,\n      PartitionSpec spec,\n      SerializableConfiguration conf,\n      MetricsConfig metricsConfig,\n      NameMapping mapping,\n      boolean ignoreMissingFiles,\n      ExecutorService service) {\n    try {\n      return TableMigrationUtil.listPartition(\n          partition.values,","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkTableUtil.java#L139-L175","documentation":"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.","triggerScenarios":"Calling SparkTableUtil.getPartitions(sparkSession, tableIdent, partitionFilter) with a TableIdentifier whose database does not exist in the Spark catalog (e.g. catalog.listPartitions throws NoSuchDatabaseException).","commonSituations":"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.","solutions":["Verify the database exists: spark.sessionState.catalog().databaseExists(db) or SHOW DATABASES, and correct the identifier (use catalog.db.table fully qualified).","Ensure the Spark session is configured with the right catalog/metastore (spark.sql.catalog.* and hive metastore URIs) where the database actually exists.","Catch the resulting unchecked exception (NoSuchDatabaseException cause) and handle missing-DB as a controlled failure path."],"exampleFix":"// before\nList<SparkPartition> parts = SparkTableUtil.getPartitions(spark, new org.apache.spark.sql.catalyst.TableIdentifier(\"tbl\", Some.apply(\"wrong_db\")), null);\n// after\nif (!spark.catalog().databaseExists(\"wrong_db\")) { throw new IllegalArgumentException(\"database wrong_db does not exist\"); }\nList<SparkPartition> parts = SparkTableUtil.getPartitions(spark, new org.apache.spark.sql.catalyst.TableIdentifier(\"tbl\", Some.apply(\"right_db\")), null);","handlingStrategy":"validation","validationCode":"TableIdentifier ident = ...;\nif (!spark.catalog().databaseExists(ident.database().get())) {\n  throw new IllegalArgumentException(\"Database not found: \" + ident.database().get());\n}","typeGuard":null,"tryCatchPattern":"try { SparkTableUtil.getPartitions(spark, ident, null); } catch (RuntimeException e) { if (e.getCause() instanceof NoSuchDatabaseException) { /* handle missing db */ } else throw e; }","preventionTips":["Always fully qualify identifiers as catalog.db.table","Check databaseExists before catalog operations","Verify Spark session points at the intended metastore"],"tags":["spark","catalog","database-not-found","unchecked-exception"],"backgroundTag":"entity-not-found","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}