apache/iceberg · error

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

Thrown when the spark.sql iceberg view schema-binding-mode property is set to a value other than 'binding' or 'compensation' (case-insensitive; the value is trimmed). The library validates this config because view schema evolution behavior must be one of the two supported modes.

Source

Thrown at spark/v3.5/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.invalidViewText(viewText, name)
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set the property to exactly 'binding' or 'compensation' (case-insensitive): SET spark.sql-view-schema-binding-mode=compensation;
2. Unset the property to use the library default instead of supplying a custom value
3. Check the SparkSQLProperties constants in your Iceberg version for the accepted values

Example fix

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

val mode = spark.conf.getOption("spark.sql-view-schema-binding-mode")
val allowed = Set("binding", "compensation")
mode.foreach(m => require(allowed.contains(m.trim.toLowerCase), s"Invalid view schema binding mode: $m"))

def isValidViewSchemaMode(m: String): Boolean =
  Set("binding", "compensation").contains(m.trim.toLowerCase)

When it happens

Trigger: Setting SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE (spark.sql-view-schema-binding-mode style config) via SQLConf, SparkConf, or session config to any unrecognized string such as 'bind', 'compat', or 'none'.

Common situations: Typos in spark config files or SQL SET commands; copy-pasted config from a different engine; documentation drift across Iceberg/Spark versions where mode names changed.

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

• Invalid value for ${SparkSQLProperties.VIEW_SCHEMA_BINDING_M
• ALTER VIEW <viewName> AS is not supported. Use CREATE OR REP
• max_concurrent_deletes only works with FileIOs that do not s
• max_concurrent_deletes only works with FileIOs that do not s
• Invalid rewrite job order name: %s

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