apache/iceberg · error · RuntimeException

Unrecognized WRITE_DISTRIBUTION_MODE:

Error message

Unrecognized WRITE_DISTRIBUTION_MODE: 

What it means

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.

Source

Thrown at flink/v2.3/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. Set write.distribution-mode to none, hash, or range (or use DistributionMode.NONE/HASH/RANGE constants)
2. Align Iceberg connector and runtime jar versions so the enum values match what the table metadata uses
3. Force the mode explicitly with builder.distributionMode(...) to bypass table-property-driven resolution

Example fix

// before
tbl.properties().put(TableProperties.WRITE_DISTRIBUTION_MODE, "custom-mode");
// after
tbl.properties().put(TableProperties.WRITE_DISTRIBUTION_MODE, DistributionMode.NONE.modeName());

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

When it happens

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

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

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/f992746c14a22636. Report an issue: GitHub.