apache/iceberg · error · RuntimeException

Unrecognized WRITE_DISTRIBUTION_MODE:

Error message

Unrecognized WRITE_DISTRIBUTION_MODE: 

What it means

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.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/sink/FlinkSink.java:721

            shuffleStream = shuffleStream.uid(uidPrefix + "-shuffle");
          }

          return shuffleStream
              .partitionCustom(new RangePartitioner(iSchema, sortOrder), r -> r)
              .flatMap(
                  (FlatMapFunction<StatisticsOrRecord, RowData>)
                      (statisticsOrRecord, out) -> {
                        if (statisticsOrRecord.hasRecord()) {
                          out.collect(statisticsOrRecord.record());
                        }
                      })
              // Set the parallelism same as writerParallelism to
              // promote operator chaining with the downstream writer operator
              .setParallelism(writerParallelism)
              .returns(RowData.class);

        default:
          throw new RuntimeException("Unrecognized " + WRITE_DISTRIBUTION_MODE + ": " + writeMode);
      }
    }
  }

  /**
   * Clean up after removing {@link Builder#tableSchema}
   *
   * @deprecated since 1.10.0, will be removed in 2.0.0. Use {@link #toFlinkRowType(Schema,
   *     ResolvedSchema)} instead.
   */
  @Deprecated
  static RowType toFlinkRowType(Schema schema, TableSchema requestedSchema) {
    if (requestedSchema != null) {
      // Convert the flink schema to iceberg schema using the table schema as the reference.
      Schema writeSchema = FlinkSchemaUtil.convert(schema, requestedSchema);
      TypeUtil.validateWriteSchema(schema, writeSchema, true, true);

      // We use this flink schema to read values from RowData. The flink's TINYINT and SMALLINT will

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. 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
2. Upgrade the Iceberg Flink runtime to match the version that wrote the table metadata if the mode is a newer valid value
3. Explicitly override the mode at sink creation via Builder.distributionMode(DistributionMode.HASH) instead of relying on table properties

Example fix

// before (table property)
tbl.properties().put(TableProperties.WRITE_DISTRIBUTION_MODE, "quad");
// after
tbl.properties().put(TableProperties.WRITE_DISTRIBUTION_MODE, DistributionMode.HASH.modeName());

String mode = table.properties().getOrDefault("write.distribution-mode", "none");
if (!java.util.Arrays.asList("none", "hash", "range").contains(mode.toLowerCase(Locale.ROOT))) {
  throw new IllegalArgumentException("write.distribution-mode must be none|hash|range, got: " + mode);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unrecognized WRITE_DISTRIBUTION_MODE:
• Unknown file format %s
• The configured equality field column IDs {} are not matched
• Fallback to use 'none' distribution mode, because there are
• Hash distribute rows by equality fields, even though {}=rang

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/1c742ad60133304c. Report an issue: GitHub.