What causes "Invalid session catalog: ${sparkSessionCatalog}" in apache/iceberg?

Choose a delegate catalog implementation that implements TableCatalog, FunctionCatalog, and SupportsNamespaces (e.g. the built-in Spark in-memory catalog).

apache/iceberg · error · IllegalArgumentException

Invalid session catalog: ${sparkSessionCatalog}

Error message

Invalid session catalog: ${sparkSessionCatalog}

What it means

Thrown by SparkSessionCatalog.setDelegateCatalog when the CatalogPlugin configured as the Spark session catalog does not implement all three required interfaces: TableCatalog, FunctionCatalog, and SupportsNamespaces. The Iceberg session catalog wrapper can only delegate to catalogs providing that full surface.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkSessionCatalog.java:370

      return;
    }

    Preconditions.checkArgument(
        catalogHmsUri.equals(envHmsUri),
        "Inconsistent Hive metastore URIs: %s (Spark session) != %s (spark_catalog)",
        envHmsUri,
        catalogHmsUri);
  }

  @Override
  @SuppressWarnings("unchecked")
  public void setDelegateCatalog(CatalogPlugin sparkSessionCatalog) {
    if (sparkSessionCatalog instanceof TableCatalog
        && sparkSessionCatalog instanceof FunctionCatalog
        && sparkSessionCatalog instanceof SupportsNamespaces) {
      this.sessionCatalog = (T) sparkSessionCatalog;
    } else {
      throw new IllegalArgumentException("Invalid session catalog: " + sparkSessionCatalog);
    }
  }

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

  private boolean useIceberg(String provider) {
    if (provider == null || "iceberg".equalsIgnoreCase(provider)) {
      return true;
    } else if (createParquetAsIceberg && "parquet".equalsIgnoreCase(provider)) {
      return true;
    } else if (createAvroAsIceberg && "avro".equalsIgnoreCase(provider)) {
      return true;
    } else if (createOrcAsIceberg && "orc".equalsIgnoreCase(provider)) {
      return true;
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

Choose a delegate catalog implementation that implements TableCatalog, FunctionCatalog, and SupportsNamespaces (e.g. the built-in Spark in-memory catalog).
Update or wrap the custom CatalogPlugin to add the missing interfaces.
If the catalog cannot satisfy the interface contract, do not register it as the session catalog; register it as a named catalog instead.

Example fix

// before
spark.sql.session.catalog.impl  com.example.MinimalCatalog  // not a FunctionCatalog
// after
spark.sql.session.catalog.impl  org.apache.spark.sql.catalog.inMemoryTableCatalog

Defensive patterns

Strategy: validation

Validate before calling

CatalogPlugin c = /* configured delegate */;
boolean ok = c instanceof TableCatalog && c instanceof FunctionCatalog && c instanceof SupportsNamespaces;

Type guard

boolean isValidSessionCatalog(CatalogPlugin c) {
  return c instanceof TableCatalog && c instanceof FunctionCatalog && c instanceof SupportsNamespaces;
}

Try / catch

try { sessionCatalog.setDelegateCatalog(plugin); } catch (IllegalArgumentException e) { LOG.error("delegate catalog missing required interfaces", e); }

Prevention

Verify the delegate class implements TableCatalog, FunctionCatalog, and SupportsNamespaces before registering it.
Prefer built-in catalogs (in-memory, Hive) as session catalog delegates.
Add an integration test that initializes the session catalog with the configured delegate at startup.

When it happens

Trigger: Setting spark.sql.catalog.<name>.impl (the session catalog delegate) to a CatalogPlugin implementation that is missing TableCatalog, FunctionCatalog, or SupportsNamespaces.

Common situations: Configuring spark.sql.session.catalog or sessionCatalog config with a custom catalog that only supports tables; using an older or minimal catalog implementation as the session-wide default catalog.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/f97923f637c0f2d9. Report an issue: GitHub.