apache/iceberg · error · NoSuchTableException

org.apache.iceberg.exceptions.NoSuchTableException:

Error message

org.apache.iceberg.exceptions.NoSuchTableException:

What it means

SparkCachedTableCatalog.load throws NoSuchTableException when SparkTableCache.get(key) returns null — i.e. the requested table was never cached (or was evicted). Only identifiers whose first field matches a cache key can be loaded.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCachedTableCatalog.java:142

  }

  @Override
  public String name() {
    return name;
  }

  private SparkTable load(Identifier ident) throws NoSuchTableException {
    Preconditions.checkArgument(
        ident.namespace().length == 0, CLASS_NAME + " does not support namespaces");

    Pair<String, List<String>> parsedIdent = parseIdent(ident);
    String key = parsedIdent.first();
    TableLoadOptions options = parseLoadOptions(parsedIdent.second());

    Table table = TABLE_CACHE.get(key);

    if (table == null) {
      throw new NoSuchTableException(ident);
    }

    if (options.isTableRewrite()) {
      return new SparkTable(table, null, false, true);
    }

    if (options.snapshotId() != null) {
      return new SparkTable(table, options.snapshotId(), false);
    } else if (options.asOfTimestamp() != null) {
      return new SparkTable(
          table, SnapshotUtil.snapshotIdAsOfTime(table, options.asOfTimestamp()), false);
    } else if (options.branch() != null) {
      Snapshot branchSnapshot = table.snapshot(options.branch());
      Preconditions.checkArgument(
          branchSnapshot != null,
          "Cannot find snapshot associated with branch name: %s",
          options.branch());
      return new SparkTable(table, branchSnapshot.snapshotId(), false);

View on GitHub (pinned to 86d9c8fc54)

Solutions

Ensure the table was cached via SparkTableCache with the exact key used in the identifier
Reload the table into the cache from the real catalog before querying
Check the identifier format: first field must equal the cache key

Example fix

// before
spark.table("cached_catalog.wrong_key")
// after
// cache the table first, then use the exact key
spark.table("cached_catalog." + correctCacheKey)

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure the cache holds the key before loading
if (SparkTableCache.get().get(cacheKey) == null) {
  // populate the cache from the real catalog first
}

Try / catch

try { return cachedCatalog.loadTable(ident); } catch (NoSuchTableException e) { /* re-cache from the real catalog or surface a clear message */ }

Prevention

Always populate SparkTableCache before referencing identifiers through this catalog
Use the exact cache key as the first identifier field
Account for cache eviction between long-running statements

When it happens

Trigger: Querying a table identifier bound to the cached catalog whose cache key is absent: wrong cache key in the identifier, cache never populated, or entry evicted between statements.

Common situations: Referencing a cached table after session restart or cache clear; typo in the cached identifier; another job evicting cache entries concurrently.

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