apache/iceberg · error · RuntimeException

Unrecognized write.distribution-mode:

Error message

Unrecognized write.distribution-mode: 

What it means

In IcebergSink's write-distribution dispatch, an unrecognized DistributionMode value reaches the default branch and throws this RuntimeException. Only NONE, HASH and RANGE are implemented for the pre-write topology of the new sink API.

Source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java:983

    }
  }

  private DataStream<RowData> distributeDataStream(DataStream<RowData> input) {
    DistributionMode mode = flinkWriteConf.distributionMode();
    Schema schema = table.schema();
    PartitionSpec spec = table.spec();
    SortOrder sortOrder = table.sortOrder();

    LOG.info("Write distribution mode is '{}'", mode.modeName());
    switch (mode) {
      case NONE:
        return distributeDataStreamByNoneDistributionMode(input, schema);
      case HASH:
        return distributeDataStreamByHashDistributionMode(input, schema, spec);
      case RANGE:
        return distributeDataStreamByRangeDistributionMode(input, schema, spec, sortOrder);
      default:
        throw new RuntimeException("Unrecognized " + WRITE_DISTRIBUTION_MODE + ": " + mode);
    }
  }

  private DataStream<RowData> distributeDataStreamByNoneDistributionMode(
      DataStream<RowData> input, Schema iSchema) {
    if (equalityFieldIds.isEmpty()) {
      return input;
    } else {
      LOG.info("Distribute rows by equality fields, because there are equality fields set");
      return input.keyBy(new EqualityFieldKeySelector(iSchema, flinkRowType, equalityFieldIds));
    }
  }

  private DataStream<RowData> distributeDataStreamByHashDistributionMode(
      DataStream<RowData> input, Schema iSchema, PartitionSpec partitionSpec) {
    if (equalityFieldIds.isEmpty()) {
      if (partitionSpec.isUnpartitioned()) {
        LOG.warn(

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Reset the property: ALTER TABLE t SET TBLPROPERTIES ('write.distribution-mode'='none'|'hash'|'range') or unset it.
2. Match the iceberg-flink-runtime version to the engine version that created the table.
3. Confirm equality-field/partition settings so the sink can pick a supported mode automatically.

Example fix

// before
properties.put("write.distribution-mode", "broadcast");
// after
properties.put("write.distribution-mode", "hash");

DistributionMode mode = DistributionMode.fromName(
    table.properties().getOrDefault("write.distribution-mode", "none"));
if (mode != DistributionMode.NONE && mode != DistributionMode.HASH && mode != DistributionMode.RANGE) {
  throw new IllegalArgumentException("unsupported mode: " + mode);
}

try {
  sink.append();
} catch (RuntimeException e) {
  if (e.getMessage().contains(WRITE_DISTRIBUTION_MODE)) {
    // reset the table property and resubmit
  }
  throw e;
}

When it happens

Trigger: A table's write.distribution-mode property parses to a DistributionMode the sink cannot handle — practically, a table property set to an invalid string that produced an unexpected enum mapping, or a newer enum constant read by an older runtime.

Common situations: Hand-set table properties (typos or custom values); tables written by newer engines with modes unknown to the deployed iceberg-flink-runtime; copy-pasted configs from Spark jobs.

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:
• ${tableName}: Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mod
• Unrecognized :
• Unknown file format %s
• : Unrecognized write.distribution-mode:

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