apache/iceberg · error · IllegalArgumentException

Invalid session catalog: sparkSessionCatalog

Error message

Invalid session catalog: sparkSessionCatalog

What it means

Thrown by SparkSessionCatalog.setDelegateCatalog when the CatalogPlugin provided as the session (delegate) catalog does not simultaneously implement TableCatalog, FunctionCatalog, and SupportsNamespaces. The session catalog must be a full-featured catalog, so partial implementations are rejected at initialization.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkSessionCatalog.java:369

      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

1. Configure a delegate catalog that implements all three interfaces: TableCatalog, FunctionCatalog, and SupportsNamespaces.
2. Use a built-in catalog (e.g. Spark's V2SessionCatalog or HiveCatalog) as the delegate.
3. Upgrade/fix the custom catalog implementation to add the missing interfaces.
4. Verify the class name in spark.sql.catalog.<session-catalog-name> is the intended implementation.

Example fix

// before
spark.conf.set("spark.sql.catalog.spark_catalog", "com.example.PartialCatalog");
// after
spark.conf.set("spark.sql.catalog.spark_catalog", "org.apache.iceberg.spark.SparkSessionCatalog");
spark.conf.set("spark.sql.catalog.spark_catalog.catalog-impl", "org.apache.iceberg.hive.HiveCatalog");

if (!(plugin instanceof TableCatalog && plugin instanceof FunctionCatalog && plugin instanceof SupportsNamespaces)) { throw new IllegalArgumentException("delegate catalog missing required interfaces"); }

boolean validDelegate = plugin instanceof TableCatalog && plugin instanceof FunctionCatalog && plugin instanceof SupportsNamespaces;

try { sessionCatalog.setDelegateCatalog(plugin); } catch (IllegalArgumentException e) { /* substitute a full-featured delegate catalog */ }

When it happens

Trigger: Configuring spark.sql.catalog.<name> (the delegate under spark.sql.catalog.spark_catalog delegate setup / setDelegateCatalog) with a plugin class that implements only some of TableCatalog, FunctionCatalog, SupportsNamespaces — e.g. a custom catalog lacking function support.

Common situations: Pointing SparkSessionCatalog at a third-party or custom CatalogPlugin; misconfigured spark_catalog delegation after upgrading Spark; using an old catalog implementation lacking FunctionCatalog; test code passing a stub catalog plugin.

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

• Cannot use catalog %s(%s): not a TableCatalog
• Invalid session catalog: ${sparkSessionCatalog}
• Invalid session catalog:
• Invalid session catalog: ${sparkSessionCatalog}
• Failed to load catalog: {}

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