apache/iceberg · error · IllegalArgumentException

Invalid value for ${SparkSQLProperties.VIEW_SCHEMA_BINDING_M

Error message

Invalid value for ${SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE}: $mode, expected ${SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING} or ${SparkSQLProperties.VIEW_SCHEMA_MODE_COMPENSATION}

What it means

Iceberg views support schema binding modes configured via spark.sql-view-schema-binding-mode (SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE). NormalizeMode accepts only 'binding' or 'compensation' (case-insensitive); any other string is rejected with this IllegalArgumentException at analysis time.

Source

Thrown at spark/v4.1/spark-extensions/src/main/scala/org/apache/spark/sql/catalyst/analysis/ResolveViews.scala:145

    SubqueryAlias(nameParts, Project(aliases, rewritten))
  }

  // Read on every resolution rather than cached, so that SET takes effect within a session.
  private def viewSchemaMode: String =
    parseSchemaBindingMode(
      conf.getConfString(
        SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE,
        SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING))

  private def parseSchemaBindingMode(mode: String): String = {
    val normalized = mode.trim
    if (normalized.equalsIgnoreCase(SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING)) {
      SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING
    } else if (normalized.equalsIgnoreCase(SparkSQLProperties.VIEW_SCHEMA_MODE_COMPENSATION)) {
      SparkSQLProperties.VIEW_SCHEMA_MODE_COMPENSATION
    } else {
      throw new IllegalArgumentException(
        s"Invalid value for ${SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE}: $mode, expected " +
          s"${SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING} or " +
          s"${SparkSQLProperties.VIEW_SCHEMA_MODE_COMPENSATION}")
    }
  }

  private def parseViewText(name: String, viewText: String): LogicalPlan = {
    val origin = Origin(objectType = Some("VIEW"), objectName = Some(name))

    try {
      CurrentOrigin.withOrigin(origin) {
        spark.sessionState.sqlParser.parseQuery(viewText)
      }
    } catch {
      case _: ParseException =>
        throw QueryCompilationErrors.invalidViewNameError(name)
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set the conf to exactly 'binding' or 'compensation' (case-insensitive): SET spark.sql-view-schema-binding-mode=binding
2. Check spelling/whitespace of the value (leading/trailing whitespace is trimmed, but the word must match)
3. Remove the SET line entirely to use the default behavior if schema binding customization isn't needed
4. Verify the property name and accepted values against the Iceberg version in use

Example fix

// before
SET spark.sql-view-schema-binding-mode=strict
// after
SET spark.sql-view-schema-binding-mode=compensation

val valid = Set("binding", "compensation")
val mode = spark.conf.getOption("spark.sql-view-schema-binding-mode")
require(mode.forall(m => valid.contains(m.trim.toLowerCase(java.util.Locale.ROOT))), s"Invalid spark.sql-view-schema-binding-mode: $mode")

try { spark.sql(query) } catch { case e: IllegalArgumentException if e.getMessage.contains("VIEW_SCHEMA_BINDING_MODE") => spark.conf.set("spark.sql-view-schema-binding-mode", "binding"); retry() }

When it happens

Trigger: Setting the SQL conf `spark.sql-view-schema-binding-mode` to an unrecognized value (e.g. 'strict', 'v1', typo like 'bindng') and then running view DDL/queries that resolve Iceberg views via ResolveViews.

Common situations: Typos in SET commands; copying config from docs for a different property; using values from older Iceberg versions where the property didn't exist.

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 parse order: parser is not an Iceberg ExtendedParser
• ALTER VIEW <viewName> AS is not supported. Use CREATE OR REP
• CREATE_VIEW_COLUMN_ARITY_MISMATCH.NOT_ENOUGH_DATA_COLUMNS
• CREATE_VIEW_COLUMN_ARITY_MISMATCH.TOO_MANY_DATA_COLUMNS
• Recursive cycle in view detected: %s (cycle: %s)

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