{"record":{"id":"b9c965a6714d8563","repo":"apache/iceberg","slug":"unrecognized-write-distribution-mode-mode-b9c965","errorCode":null,"errorMessage":"Unrecognized write.distribution-mode: ${mode}","messagePattern":"Unrecognized write\\.distribution-mode: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink/v2.1/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.1/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java#L965-L1001","documentation":"Thrown by IcebergSink when the write.distribution-mode table property resolves to a value the sink does not recognize. Valid values are none, hash, and range (case handled by DistributionMode). The sink uses this property to decide how to shuffle rows before writing; an unknown value cannot be mapped to a distribution strategy.","triggerScenarios":"Setting the table property write.distribution-mode to a typo or arbitrary string (e.g. 'hashes', 'key', 'NONE ' with whitespace handled upstream, or custom text) and then running a Flink IcebergSink write job.","commonSituations":"Hand-edited table properties, migration from another engine where a different distribution value was set, copy-pasted config from documentation for a different table, or programmatic property construction with a bad enum string.","solutions":["Set write.distribution-mode to one of: none, hash, or range (e.g. ALTER TABLE ... SET TBLPROPERTIES ('write.distribution-mode'='hash')).","Remove the write.distribution-mode property entirely so the sink picks its default mode.","Check DistributionMode.fromName handling and confirm no surrounding whitespace or case-mangling was applied when the property was written.","If using Flink write distribution options, prefer the sink's mode option over raw table properties to avoid invalid values."],"exampleFix":"// before: table property 'write.distribution-mode' = 'hash-by-key'\n// after\nALTER TABLE db.t SET TBLPROPERTIES ('write.distribution-mode'='hash');","handlingStrategy":"validation","validationCode":"String mode = table.properties().getOrDefault(\"write.distribution-mode\", \"none\");\nif (!Set.of(\"none\", \"hash\", \"range\").contains(mode.toLowerCase(Locale.ROOT))) {\n  throw new IllegalArgumentException(\"write.distribution-mode must be none|hash|range, got: \" + mode);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set write.distribution-mode from the documented enum values.","Prefer sink options/API over hand-editing table properties.","Validate table properties after programmatic construction before submitting jobs."],"tags":["flink","sink","table-properties","invalid-enum"],"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-14T21:17:11.552Z"}