apache/iceberg · error · IllegalArgumentException

Invalid session catalog:

Error message

Invalid session catalog: 

What it means

setDelegateCatalog validates that the Spark session catalog plugin implements TableCatalog, FunctionCatalog, and SupportsNamespaces before delegating to it; otherwise it throws IllegalArgumentException. The delegate must support all three interfaces for SparkSessionCatalog to proxy table, function, and namespace operations.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkSessionCatalog.java:411

      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. Set the delegate to a catalog that implements TableCatalog, FunctionCatalog, and SupportsNamespaces (e.g. Spark's built-in V2SessionCatalog)
2. Fix the spark.sql.catalog.<name>.delegate config value to point at a fully featured catalog plugin
3. Extend your custom catalog to implement the three required interfaces

Example fix

// before
spark.sql.catalog.spark_catalog.delegate=com.example.MinimalCatalog
// after
spark.sql.catalog.spark_catalog.delegate=org.apache.spark.sql.connector.catalog.V2SessionCatalog

// validate delegate capabilities before wiring
boolean valid = plugin instanceof TableCatalog
    && plugin instanceof FunctionCatalog
    && plugin instanceof SupportsNamespaces;

boolean isUsableDelegate(CatalogPlugin p) {
  return p instanceof TableCatalog && p instanceof FunctionCatalog && p instanceof SupportsNamespaces;
}

try {
  sessionCatalog.setDelegateCatalog(plugin);
} catch (IllegalArgumentException e) {
  // log which interface is missing and use a default delegate
}

When it happens

Trigger: Configuring spark.sql.catalog.<name>.delegate to a CatalogPlugin that lacks one of the required interfaces (e.g. a custom catalog that is not a FunctionCatalog or SupportsNamespaces); wiring a legacy or minimal catalog implementation.

Common situations: Custom session-catalog plugins; misconfigured spark.sql.catalog.<name>.delegate pointing at an incompatible catalog class; upgrading Iceberg where delegate requirements are enforced more strictly.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot use catalog %s(%s): not a TableCatalog
• Invalid session catalog: sparkSessionCatalog
• Invalid session catalog: ${sparkSessionCatalog}
• Unsupported isolation level: " + isolationLevel
• Failed to load catalog: {}

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