apache/beam · error · RuntimeException

Encountered a problem fetching table {} from cache.

Error message

Encountered a problem fetching table {} from cache.

What it means

TableCache wraps a Guava/Caffeine-style LoadingCache of Iceberg CachedTable entries. When the cache loader throws, the cache library wraps the cause in an ExecutionException or UncheckedExecutionException. If the underlying cause is not a RuntimeException, TableCache re-throws it wrapped in this generic RuntimeException so the original failure (e.g. an Iceberg loader failure while resolving the table) is preserved with context about which table identifier could not be fetched.

Source

Thrown at sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/TableCache.java:112

  /** Returns the cached table, using the loader on a miss and refreshing stale entries. */
  public static Table getAndRefreshIfStale(
      IcebergCatalogConfig catalogConfig, TableIdentifier identifier, Callable<Table> loader) {
    CachedTable cachedTable = getEntry(catalogConfig, identifier, loader);
    cachedTable.refreshIfOlderThan(Instant.now().minus(DEFAULT_REFRESH_INTERVAL));
    return cachedTable.table;
  }

  private static CachedTable getEntry(
      IcebergCatalogConfig catalogConfig, TableIdentifier identifier, Callable<Table> loader) {
    CacheKey key = new CacheKey(catalogConfig, identifier);
    try {
      return TABLES.get(key, () -> new CachedTable(loader.call(), Instant.now()));
    } catch (ExecutionException | UncheckedExecutionException e) {
      if (e.getCause() instanceof RuntimeException) {
        throw (RuntimeException) e.getCause();
      }
      throw new RuntimeException(
          "Encountered a problem fetching table " + identifier + " from cache.", e);
    }
  }

  @VisibleForTesting
  static long size() {
    return TABLES.size();
  }

  @VisibleForTesting
  static void invalidateAll() {
    TABLES.invalidateAll();
  }

  @VisibleForTesting
  static void put(
      IcebergCatalogConfig catalogConfig,
      TableIdentifier identifier,

View on GitHub (pinned to 12126d8942)

Solutions

1. Inspect the wrapped cause (getCause chain) to find the real loader failure and fix it (catalog config, credentials, or table existence).
2. Verify the table identifier and catalog configuration are correct and the table exists in the target catalog.
3. Check metastore/warehouse connectivity and credentials (Hive metastore, Glue, Nessie, etc.) before the pipeline runs.
4. If a checked exception from the loader is expected, wrap the loader logic to throw a RuntimeException with a clearer message instead of relying on the generic wrapper.

Example fix

// before
catalog.loadTable(identifier); // throws checked-ish failure, surfaces as generic RuntimeException
// after
if (!catalog.tableExists(identifier)) {
  throw new RuntimeException("Table not found in catalog: " + identifier);
}
Table table = catalog.loadTable(identifier);

if (!catalog.tableExists(tableIdentifier)) {
  throw new IllegalArgumentException("Table missing from catalog: " + tableIdentifier);
}

if (e.getCause() instanceof RuntimeException rte) { throw rte; } // inspect the real cause first

try {
  table = TableCache.get(id, loader);
} catch (RuntimeException e) {
  Throwable cause = e.getCause();
  // route on cause type: missing table, auth failure, metastore outage
  throw new IllegalStateException("Table cache load failed for " + id, cause);
}

When it happens

Trigger: Calling TableCache.get(identifier, loader) or cachedTable(...) when the loader.call() that loads the Iceberg table throws a checked/ non-Runtime exception (e.g. Iceberg's table loading fails due to a missing table, bad metadata location, or metastore/warehouse connectivity problem), and the cause is not a RuntimeException.

Common situations: Iceberg catalog misconfiguration (wrong warehouse URI, missing metastore connection), table deleted between listing and reading, corrupted metadata.json pointer, or transient object-store auth failures during table load in Beam Iceberg sink/source pipelines.

Related errors

• Could not set a field in the BeamRowWrapper because rowData
• smallBatchTag and largeBatchTag must not be null
• Unsupported Beam type for Iceberg timestamp with timezone: {
• Received null value for required field '{fieldName}'.
• Unsupported row type: {valueClass}

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/d0d195e5e61499fa. Report an issue: GitHub.