apache/iceberg · error · RuntimeException

Couldn't load table '%s' in catalog '%s'

Error message

Couldn't load table '%s' in catalog '%s'

What it means

BaseProcedure.loadSparkTable resolves a table identifier through the given Spark catalog and casts it to SparkTable. When the catalog throws NoSuchTableException, the procedure wraps it in a RuntimeException reporting the table identifier and catalog name, because the procedure cannot proceed without the target table.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/procedures/BaseProcedure.java:175

    Preconditions.checkArgument(
        identifierAsString != null && !identifierAsString.isEmpty(),
        "Cannot handle an empty identifier for argument %s",
        argName);

    return Spark3Util.catalogAndIdentifier(
        "identifier for arg " + argName, spark, identifierAsString, catalog);
  }

  protected SparkTable loadSparkTable(Identifier ident) {
    try {
      Table table = tableCatalog.loadTable(ident);
      ValidationException.check(
          table instanceof SparkTable, "%s is not %s", ident, SparkTable.class.getName());
      return (SparkTable) table;
    } catch (NoSuchTableException e) {
      String errMsg =
          String.format("Couldn't load table '%s' in catalog '%s'", ident, tableCatalog.name());
      throw new RuntimeException(errMsg, e);
    }
  }

  protected Dataset<Row> loadRows(Identifier tableIdent, Map<String, String> options) {
    String tableName = Spark3Util.quotedFullIdentifier(tableCatalog().name(), tableIdent);
    return spark().read().options(options).table(tableName);
  }

  protected void refreshSparkCache(Identifier ident, Table table) {
    CacheManager cacheManager = spark.sharedState().cacheManager();
    DataSourceV2Relation relation =
        DataSourceV2Relation.create(table, Option.apply(tableCatalog), Option.apply(ident));
    cacheManager.recacheByPlan(spark, relation);
  }

  protected Expression filterExpression(Identifier ident, String where) {
    try {
      String name = Spark3Util.quotedFullIdentifier(tableCatalog.name(), ident);

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Verify the table exists: SHOW TABLES IN <catalog>.<namespace> and check the exact name
  2. Use the fully qualified identifier including catalog: catalog.namespace.table
  3. Check spark.sql.defaultCatalog / USE statements so the unqualified name resolves to the right catalog
  4. Catch the RuntimeException around CALL if you need to handle missing tables gracefully

Example fix

// before
CALL catalog.system.rewrite_data_files(table => 'db.tbl'); -- tbl missing
// after
-- verify first: SHOW TABLES IN catalog.db;
CALL catalog.system.rewrite_data_files(table => 'catalog.db.tbl');
Defensive patterns

Strategy: try-catch

Validate before calling

// verify existence before the CALL
spark.sql(s"SHOW TABLES IN $catalog.$namespace").filter(col("name") === tableName)

Try / catch

try { spark.sql(procedureCall) } catch { case e: RuntimeException if e.getMessage.startsWith("Couldn't load table") => /* handle missing table */ }

Prevention

When it happens

Trigger: Calling a procedure (e.g. rewrite_data_files, expire_snapshots, remove_orphan_files) with a TABLE identifier that does not exist, is misspelled, or lives in a different catalog/namespace than specified.

Common situations: Typos in table names; forgetting the catalog prefix when multiple catalogs are configured (spark.sql.catalog.*); table dropped concurrently; wrong namespace; case-sensitivity issues in identifiers.

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