{"record":{"id":"1c742ad60133304c","repo":"apache/iceberg","slug":"unrecognized-write-distribution-mode-1c742a","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/FlinkSink.java","lineNumber":721,"sourceCode":"            shuffleStream = shuffleStream.uid(uidPrefix + \"-shuffle\");\n          }\n\n          return shuffleStream\n              .partitionCustom(new RangePartitioner(iSchema, sortOrder), r -> r)\n              .flatMap(\n                  (FlatMapFunction<StatisticsOrRecord, RowData>)\n                      (statisticsOrRecord, out) -> {\n                        if (statisticsOrRecord.hasRecord()) {\n                          out.collect(statisticsOrRecord.record());\n                        }\n                      })\n              // Set the parallelism same as writerParallelism to\n              // promote operator chaining with the downstream writer operator\n              .setParallelism(writerParallelism)\n              .returns(RowData.class);\n\n        default:\n          throw new RuntimeException(\"Unrecognized \" + WRITE_DISTRIBUTION_MODE + \": \" + writeMode);\n      }\n    }\n  }\n\n  /**\n   * Clean up after removing {@link Builder#tableSchema}\n   *\n   * @deprecated since 1.10.0, will be removed in 2.0.0. Use {@link #toFlinkRowType(Schema,\n   *     ResolvedSchema)} instead.\n   */\n  @Deprecated\n  static RowType toFlinkRowType(Schema schema, TableSchema requestedSchema) {\n    if (requestedSchema != null) {\n      // Convert the flink schema to iceberg schema using the table schema as the reference.\n      Schema writeSchema = FlinkSchemaUtil.convert(schema, requestedSchema);\n      TypeUtil.validateWriteSchema(schema, writeSchema, true, true);\n\n      // We use this flink schema to read values from RowData. The flink's TINYINT and SMALLINT will","sourceCodeStart":703,"sourceCodeEnd":739,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/sink/FlinkSink.java#L703-L739","documentation":"Thrown by FlinkSink.distributeDataStream when the table's WRITE_DISTRIBUTION_MODE property resolves to a value the sink does not recognize. The sink only supports none, hash, and range distribution modes; anything else (e.g. a typo or a mode added in a newer Iceberg version) fails this switch's default branch. It is an immediate hard failure of sink construction.","triggerScenarios":"Setting TableProperties.WRITE_DISTRIBUTION_MODE to a value other than none/hash/range via table properties (e.g. write.distribution-mode=quad) before creating a FlinkSink with a Table loaded from that metadata.","commonSituations":"Typos in write.distribution-mode when editing table properties manually; tables written by a newer Iceberg release with a new distribution mode then read by an older Flink connector; programmatic table property mutation with an invalid string.","solutions":["Check the table's write.distribution-mode property (e.g. via Spark SQL SHOW TBLPROPERTIES or Table.properties()) and correct it to none, hash, or range","Upgrade the Iceberg Flink runtime to match the version that wrote the table metadata if the mode is a newer valid value","Explicitly override the mode at sink creation via Builder.distributionMode(DistributionMode.HASH) instead of relying on table properties"],"exampleFix":"// before (table property)\ntbl.properties().put(TableProperties.WRITE_DISTRIBUTION_MODE, \"quad\");\n// after\ntbl.properties().put(TableProperties.WRITE_DISTRIBUTION_MODE, DistributionMode.HASH.modeName());","handlingStrategy":"validation","validationCode":"String mode = table.properties().getOrDefault(\"write.distribution-mode\", \"none\");\nif (!java.util.Arrays.asList(\"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":["Always set write.distribution-mode using the DistributionMode enum's modeName(), never raw strings","Validate table properties after any external tool edits metadata","Pin Iceberg connector and engine versions so both understand the same modes"],"tags":["flink","configuration","enum-parsing","sink"],"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"}