{"record":{"id":"80f95a56ad83419c","repo":"apache/iceberg","slug":"unsupported-operation-mode-mode","errorCode":null,"errorMessage":"Unsupported operation mode: ${mode}","messagePattern":"Unsupported operation mode: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/source/SparkRowLevelOperationBuilder.java","lineNumber":71,"sourceCode":"  SparkRowLevelOperationBuilder(\n      SparkSession spark, Table table, String branch, RowLevelOperationInfo info) {\n    this.spark = spark;\n    this.table = table;\n    this.branch = branch;\n    this.info = info;\n    this.mode = mode(table.properties(), info.command());\n    this.isolationLevel = isolationLevel(table.properties(), info.command());\n  }\n\n  @Override\n  public RowLevelOperation build() {\n    switch (mode) {\n      case COPY_ON_WRITE:\n        return new SparkCopyOnWriteOperation(spark, table, branch, info, isolationLevel);\n      case MERGE_ON_READ:\n        return new SparkPositionDeltaOperation(spark, table, branch, info, isolationLevel);\n      default:\n        throw new IllegalArgumentException(\"Unsupported operation mode: \" + mode);\n    }\n  }\n\n  private RowLevelOperationMode mode(Map<String, String> properties, Command command) {\n    String modeName;\n\n    switch (command) {\n      case DELETE:\n        modeName = properties.getOrDefault(DELETE_MODE, DELETE_MODE_DEFAULT);\n        break;\n      case UPDATE:\n        modeName = properties.getOrDefault(UPDATE_MODE, UPDATE_MODE_DEFAULT);\n        break;\n      case MERGE:\n        modeName = properties.getOrDefault(MERGE_MODE, MERGE_MODE_DEFAULT);\n        break;\n      default:\n        throw new IllegalArgumentException(\"Unsupported command: \" + command);","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/source/SparkRowLevelOperationBuilder.java#L53-L89","documentation":"SparkRowLevelOperationBuilder.build() maps the resolved RowLevelOperationMode to an operation. Only COPY_ON_WRITE and MERGE_ON_READ are supported; any other mode value (e.g. a mode parsed from an unrecognized property string) hits the default branch and throws IllegalArgumentException.","triggerScenarios":"Calling build() when the mode resolved from table properties (write.delete.mode / write.update.mode / write.merge.mode) is not COPY_ON_WRITE or MERGE_ON_READ — typically RowLevelOperationMode.fromName returned null or an unknown mode.","commonSituations":"A typo'd or unsupported value for the write.*.mode table property, or a newer mode enum value from a different Iceberg version being passed to an older builder.","solutions":["Check the table properties write.delete.mode, write.update.mode, write.merge.mode and set them only to 'copy-on-write' or 'merge-on-read'.","Fix typos in the mode property value (mode comparison is by exact name).","Align client and table Iceberg versions so RowLevelOperationMode.fromName cannot yield an unknown value."],"exampleFix":"// before\nALTER TABLE t SET TBLPROPERTIES ('write.merge.mode' = 'mor');\n\n// after\nALTER TABLE t SET TBLPROPERTIES ('write.merge.mode' = 'merge-on-read');","handlingStrategy":"validation","validationCode":"for (String key : List.of(\"write.delete.mode\", \"write.update.mode\", \"write.merge.mode\")) {\n  String v = table.properties().get(key);\n  if (v != null && !v.equals(\"copy-on-write\") && !v.equals(\"merge-on-read\")) {\n    throw new IllegalArgumentException(\"Invalid \" + key + \": \" + v);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  RowLevelOperation op = builder.build();\n} catch (IllegalArgumentException e) {\n  logger.error(\"Check write.*.mode table properties\", e);\n}","preventionTips":["Only set write.*.mode to 'copy-on-write' or 'merge-on-read'.","Avoid hand-editing table properties without validating values.","Check properties after catalog migrations that may copy stale values."],"tags":["spark","row-level-writes","invalid-enum-value"],"backgroundTag":"invalid-enum-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"}