{"record":{"id":"43c38781f9f41b47","repo":"apache/iceberg","slug":"unexpected-distribution-mode","errorCode":null,"errorMessage":"Unexpected distribution mode: ","messagePattern":"Unexpected distribution mode: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java","lineNumber":161,"sourceCode":"      case NONE:\n        return Distributions.unspecified();\n\n      case HASH:\n        if (table.spec().isPartitioned()) {\n          return Distributions.clustered(clustering(table));\n        } else {\n          return Distributions.clustered(FILE_CLUSTERING);\n        }\n\n      case RANGE:\n        if (table.spec().isPartitioned() || table.sortOrder().isSorted()) {\n          return Distributions.ordered(ordering(table));\n        } else {\n          return Distributions.ordered(EXISTING_ROW_ORDERING);\n        }\n\n      default:\n        throw new IllegalArgumentException(\"Unexpected distribution mode: \" + mode);\n    }\n  }\n\n  /** Builds requirements for merge-on-read DELETE, UPDATE, MERGE operations. */\n  public static SparkWriteRequirements positionDeltaRequirements(\n      Table table,\n      Command command,\n      DistributionMode mode,\n      boolean fanoutEnabled,\n      long advisoryPartitionSize) {\n\n    if (command == UPDATE || command == MERGE) {\n      Distribution distribution = positionDeltaUpdateMergeDistribution(table, mode);\n      SortOrder[] ordering = positionDeltaUpdateMergeOrdering(table, fanoutEnabled);\n      return new SparkWriteRequirements(distribution, ordering, advisoryPartitionSize);\n    } else {\n      Distribution distribution = positionDeltaDeleteDistribution(table, mode);\n      SortOrder[] ordering = fanoutEnabled ? EMPTY_ORDERING : POSITION_DELETE_ORDERING;","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L143-L179","documentation":"SparkWriteUtil.copyOnWriteDeleteUpdateDistribution builds distributions for copy-on-write DELETE/UPDATE writes per DistributionMode, with explicit branches for HASH and RANGE (and NONE handling above). An unexpected mode reaching the default branch throws IllegalArgumentException(\"Unexpected distribution mode: \" + mode).","triggerScenarios":"Calling copyOnWriteDeleteUpdateDistribution with a mode that is not NONE, HASH, or RANGE - e.g. a freshly added DistributionMode constant or a mode resolved from an invalid config value.","commonSituations":"write.distribution-mode / write.delete.distribution-mode configured to an unrecognized value; version skew introducing new enum constants not handled by this utility.","solutions":["Configure distribution mode to one of none/hash/range for CoW delete/update writes","Guard the call site by checking the resolved mode before invoking","Update the switch to handle any newly introduced DistributionMode constants"],"exampleFix":"// before\nDistribution d = SparkWriteUtil.copyOnWriteDeleteUpdateDistribution(table, mode, fanout); // throws\n// after\nif (mode == DistributionMode.HASH) {\n  d = Distributions.clustered(SparkWriteUtil.clustering(table));\n} else {\n  d = SparkWriteUtil.copyOnWriteDeleteUpdateDistribution(table, mode, fanout);\n}","handlingStrategy":"validation","validationCode":"if (mode != DistributionMode.NONE && mode != DistributionMode.HASH && mode != DistributionMode.RANGE) {\n  throw new IllegalArgumentException(\"CoW delete/update distribution requires NONE/HASH/RANGE, got: \" + mode);\n}","typeGuard":"boolean validForCoWDeleteUpdate(DistributionMode m) {\n  return EnumSet.of(DistributionMode.NONE, DistributionMode.HASH, DistributionMode.RANGE).contains(m);\n}","tryCatchPattern":"try {\n  dist = SparkWriteUtil.copyOnWriteDeleteUpdateDistribution(table, mode, fanoutEnabled);\n} catch (IllegalArgumentException e) {\n  LOG.warn(\"Mode {} unsupported, ordering rows by existing order\", mode, e);\n  dist = Distributions.ordered(SparkWriteUtil.EXISTING_ROW_ORDERING);\n}","preventionTips":["Resolve mode through SparkWriteConf rather than parsing config strings ad hoc","Restrict delete/update distribution-mode properties to documented values","Add exhaustive tests per DistributionMode for CoW paths","Bump utility code together with enum changes"],"tags":["spark","distribution","copy-on-write","enum"],"backgroundTag":"unsupported-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"}