{"record":{"id":"0bafb5e84f72a43c","repo":"apache/iceberg","slug":"unexpected-distribution-mode-mode","errorCode":null,"errorMessage":"Unexpected distribution mode: mode","messagePattern":"Unexpected distribution mode: mode","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java","lineNumber":131,"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":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkWriteUtil.java#L113-L149","documentation":"copyOnWriteDeleteUpdateDistribution() builds the distribution for copy-on-write DELETE/UPDATE operations. Supported modes are NONE and HASH (with RANGE falling through in some variants); an unrecognized mode throws IllegalArgumentException with 'Unexpected distribution mode'.","triggerScenarios":"Invoking this via SparkWriteUtil.distribution() for a CoW DELETE/UPDATE when the resolved DistributionMode is not in the handled set (e.g. RANGE where only NONE/HASH are handled here, or an unknown enum constant).","commonSituations":"Configuration like write.delete.distribution-mode=range on a Spark version where CoW delete/update only supports none/hash; custom write requirements passing an unexpected mode.","solutions":["Change the delete/update distribution-mode override to a supported value (none or hash)","Remove the operation-specific override so it falls back to the table-level supported mode","Upgrade the Iceberg Spark module for broader mode support"],"exampleFix":"// before\nspark.conf.set(\"write.delete.distribution-mode\", \"range\")\n// after\nspark.conf.set(\"write.delete.distribution-mode\", \"hash\")","handlingStrategy":"validation","validationCode":"if (mode != DistributionMode.NONE && mode != DistributionMode.HASH) {\n  throw new IllegalArgumentException(\"CoW delete/update supports only none/hash, got \" + mode);\n}","typeGuard":"boolean coWDeleteUpdateSupported = mode == DistributionMode.NONE || mode == DistributionMode.HASH;","tryCatchPattern":"try {\n  dist = SparkWriteUtil.copyOnWriteDeleteUpdateDistribution(table, mode, ...);\n} catch (IllegalArgumentException e) {\n  dist = SparkWriteUtil.copyOnWriteDeleteUpdateDistribution(table, DistributionMode.HASH, ...);\n}","preventionTips":["Avoid range distribution-mode for CoW delete/update unless your version supports it","Let unsupported per-operation overrides fall back to the table default","Unit-test planning for each distribution mode you configure"],"tags":["spark","distribution-planning","illegal-argument"],"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"}