{"record":{"id":"f992746c14a22636","repo":"apache/iceberg","slug":"unrecognized-write-distribution-mode-f99274","errorCode":null,"errorMessage":"Unrecognized WRITE_DISTRIBUTION_MODE: ","messagePattern":"Unrecognized WRITE_DISTRIBUTION_MODE: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java","lineNumber":983,"sourceCode":"    }\n  }\n\n  private DataStream<RowData> distributeDataStream(DataStream<RowData> input) {\n    DistributionMode mode = flinkWriteConf.distributionMode();\n    Schema schema = table.schema();\n    PartitionSpec spec = table.spec();\n    SortOrder sortOrder = table.sortOrder();\n\n    LOG.info(\"Write distribution mode is '{}'\", mode.modeName());\n    switch (mode) {\n      case NONE:\n        return distributeDataStreamByNoneDistributionMode(input, schema);\n      case HASH:\n        return distributeDataStreamByHashDistributionMode(input, schema, spec);\n      case RANGE:\n        return distributeDataStreamByRangeDistributionMode(input, schema, spec, sortOrder);\n      default:\n        throw new RuntimeException(\"Unrecognized \" + WRITE_DISTRIBUTION_MODE + \": \" + mode);\n    }\n  }\n\n  private DataStream<RowData> distributeDataStreamByNoneDistributionMode(\n      DataStream<RowData> input, Schema iSchema) {\n    if (equalityFieldIds.isEmpty()) {\n      return input;\n    } else {\n      LOG.info(\"Distribute rows by equality fields, because there are equality fields set\");\n      return input.keyBy(new EqualityFieldKeySelector(iSchema, flinkRowType, equalityFieldIds));\n    }\n  }\n\n  private DataStream<RowData> distributeDataStreamByHashDistributionMode(\n      DataStream<RowData> input, Schema iSchema, PartitionSpec partitionSpec) {\n    if (equalityFieldIds.isEmpty()) {\n      if (partitionSpec.isUnpartitioned()) {\n        LOG.warn(","sourceCodeStart":965,"sourceCodeEnd":1001,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java#L965-L1001","documentation":"IcebergSink's distribution-mode resolution switch throws this RuntimeException when the effective DistributionMode (from table property or builder) is not NONE, HASH, or RANGE. Like the FlinkSink variant, it is a defensive default branch against an unrecognized write distribution mode.","triggerScenarios":"Building an IcebergSink where the resolved DistributionMode enum falls outside the handled cases — practically only via a stale/foreign distribution-mode string mapped to an unknown mode, or future enum values from newer Iceberg versions.","commonSituations":"Tables configured with a distribution mode introduced after the connector's version; custom code mapping arbitrary strings into DistributionMode; mixing Iceberg jar versions on the classpath.","solutions":["Set write.distribution-mode to none, hash, or range (or use DistributionMode.NONE/HASH/RANGE constants)","Align Iceberg connector and runtime jar versions so the enum values match what the table metadata uses","Force the mode explicitly with builder.distributionMode(...) to bypass table-property-driven resolution"],"exampleFix":"// before\ntbl.properties().put(TableProperties.WRITE_DISTRIBUTION_MODE, \"custom-mode\");\n// after\ntbl.properties().put(TableProperties.WRITE_DISTRIBUTION_MODE, DistributionMode.NONE.modeName());","handlingStrategy":"validation","validationCode":"DistributionMode mode = PropertyUtil.propertyAsEnum(table.properties(), TableProperties.WRITE_DISTRIBUTION_MODE, DistributionMode.NONE);\nif (mode != DistributionMode.NONE && mode != DistributionMode.HASH && mode != DistributionMode.RANGE) {\n  throw new IllegalArgumentException(\"unsupported write.distribution-mode: \" + mode);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set the mode via builder.distributionMode(DistributionMode.X) to control resolution explicitly","Keep engine and connector Iceberg versions identical to avoid unknown enum values","Avoid hand-writing distribution-mode strings in DDL or property files"],"tags":["flink","sink","configuration","enum-parsing"],"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"}