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

The spark.view.schema-binding-mode (SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE) property accepts only two values: "binding" and "compensation" (case-insensitive, trimmed). Any other value triggers this IllegalArgumentException at analysis time when the mode is normalized.

Source

Thrown at spark/v4.0/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 property to exactly "binding" or "compensation" (any casing)
2. Remove the property to use the default behavior
3. Check the Iceberg docs for your version for supported schema-binding modes

Example fix

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

val valid = Set("binding", "compensation")
val mode = spark.conf.get("spark.view.schema.binding.mode", "")
if (mode.nonEmpty && !valid.contains(mode.trim.toLowerCase)) {
  throw new IllegalArgumentException(s"$mode is not one of $valid")
}

try {
  spark.sql("SELECT * FROM v")
} catch {
  case e: IllegalArgumentException if e.getMessage.contains("VIEW_SCHEMA_BINDING_MODE") =>
    spark.conf.set("spark.view.schema.binding.mode", "binding")
}

When it happens

Trigger: Setting the view schema binding mode to an unrecognized string, e.g. via TBLPROPERTIES/SET spark.view.schema.binding.mode=strict, or programmatically passing a bad mode into view resolution config.

Common situations: Typo in the property value; confusion with similar property names from other engines; docs/config templates using an outdated value.

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

• Renaming a view is not supported by catalog: ${catalogName}
• Unsupported Spark view dependency: ${dependency.getClass().g
• Failed to write Spark view dependencies
• Failed to parse Spark view dependencies
• Unsupported Spark view dependency type:

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