{"record":{"id":"5f190be6ea1847e5","repo":"apache/iceberg","slug":"invalid-value-for-sparksqlproperties-view-schema-5f190b","errorCode":null,"errorMessage":"Invalid value for ${SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE}: $mode, expected ${SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING} or ${SparkSQLProperties.VIEW_SCHEMA_MODE_COMPENSATION}","messagePattern":"Invalid value for (.+?): \\$mode, expected (.+?) or (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.1/spark-extensions/src/main/scala/org/apache/spark/sql/catalyst/analysis/ResolveViews.scala","lineNumber":145,"sourceCode":"\n    SubqueryAlias(nameParts, Project(aliases, rewritten))\n  }\n\n  // Read on every resolution rather than cached, so that SET takes effect within a session.\n  private def viewSchemaMode: String =\n    parseSchemaBindingMode(\n      conf.getConfString(\n        SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE,\n        SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING))\n\n  private def parseSchemaBindingMode(mode: String): String = {\n    val normalized = mode.trim\n    if (normalized.equalsIgnoreCase(SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING)) {\n      SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING\n    } else if (normalized.equalsIgnoreCase(SparkSQLProperties.VIEW_SCHEMA_MODE_COMPENSATION)) {\n      SparkSQLProperties.VIEW_SCHEMA_MODE_COMPENSATION\n    } else {\n      throw new IllegalArgumentException(\n        s\"Invalid value for ${SparkSQLProperties.VIEW_SCHEMA_BINDING_MODE}: $mode, expected \" +\n          s\"${SparkSQLProperties.VIEW_SCHEMA_MODE_BINDING} or \" +\n          s\"${SparkSQLProperties.VIEW_SCHEMA_MODE_COMPENSATION}\")\n    }\n  }\n\n  private def parseViewText(name: String, viewText: String): LogicalPlan = {\n    val origin = Origin(objectType = Some(\"VIEW\"), objectName = Some(name))\n\n    try {\n      CurrentOrigin.withOrigin(origin) {\n        spark.sessionState.sqlParser.parseQuery(viewText)\n      }\n    } catch {\n      case _: ParseException =>\n        throw QueryCompilationErrors.invalidViewNameError(name)\n    }\n  }","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.1/spark-extensions/src/main/scala/org/apache/spark/sql/catalyst/analysis/ResolveViews.scala#L127-L163","documentation":"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.","triggerScenarios":"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.","commonSituations":"Typos in SET commands; copying config from docs for a different property; using values from older Iceberg versions where the property didn't exist.","solutions":["Set the conf to exactly 'binding' or 'compensation' (case-insensitive): SET spark.sql-view-schema-binding-mode=binding","Check spelling/whitespace of the value (leading/trailing whitespace is trimmed, but the word must match)","Remove the SET line entirely to use the default behavior if schema binding customization isn't needed","Verify the property name and accepted values against the Iceberg version in use"],"exampleFix":"// before\nSET spark.sql-view-schema-binding-mode=strict\n// after\nSET spark.sql-view-schema-binding-mode=compensation","handlingStrategy":"validation","validationCode":"val valid = Set(\"binding\", \"compensation\")\nval mode = spark.conf.getOption(\"spark.sql-view-schema-binding-mode\")\nrequire(mode.forall(m => valid.contains(m.trim.toLowerCase(java.util.Locale.ROOT))), s\"Invalid spark.sql-view-schema-binding-mode: $mode\")","typeGuard":null,"tryCatchPattern":"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() }","preventionTips":["Only set the conf to 'binding' or 'compensation'","Validate SET values in deployment scripts","Don't copy this conf value from unrelated docs"],"tags":["spark","views","configuration","sql-extensions"],"backgroundTag":"invalid-config-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}