apache/iceberg · warning

Fallback to use 'none' distribution mode, because there are

Error message

Fallback to use 'none' distribution mode, because there are no equality fields set and table is unpartitioned

What it means

When 'hash' write distribution mode is requested but the sink has no equality fields configured and the target table is unpartitioned, there is no key to hash by. The sink warns and falls back to 'none' distribution, sending rows to writers round-robin instead of keying the DataStream.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java:1001

        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(
            "Fallback to use 'none' distribution mode, because there are no equality fields set "
                + "and table is unpartitioned");
        return input;
      } else {
        return input.keyBy(new PartitionKeySelector(partitionSpec, iSchema, flinkRowType));
      }
    } else {
      if (partitionSpec.isUnpartitioned()) {
        LOG.info(
            "Distribute rows by equality fields, because there are equality fields set "
                + "and table is unpartitioned");
        return input.keyBy(new EqualityFieldKeySelector(iSchema, flinkRowType, equalityFieldIds));
      } else {
        for (PartitionField partitionField : partitionSpec.fields()) {
          Preconditions.checkState(
              equalityFieldIds.contains(partitionField.sourceId()),
              "In 'hash' distribution mode with equality fields set, source column '%s' of partition field '%s' "
                  + "should be included in equality fields: '%s'",

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Remove the hash distribution setting for the unpartitioned table ('none' is appropriate for append-only unpartitioned writes).
2. If upsert semantics are needed, set .equalityFields(...) / equality field ids so hash distribution has keys.
3. Switch to partitioned writes if hashing by partition key is intended.

Example fix

// before
FlinkSink.forRowData(input)
    .table(unpartitionedTable)
    .distributionMode(DistributionMode.HASH)
    .append();
// after
FlinkSink.forRowData(input)
    .table(unpartitionedTable)
    .distributionMode(DistributionMode.NONE)
    .append();

if (distMode == DistributionMode.HASH && table.spec().isUnpartitioned()
    && (equalityFields == null || equalityFields.isEmpty())) {
  LOG.warn("HASH distribution is meaningless here; use NONE or add equality fields/partitioning");
}

When it happens

Trigger: Building an IcebergSink with DistributionMode.HASH (or write.distribution-mode=hash) on an unpartitioned table while equalityFieldIds is empty.

Common situations: Configuring hash distribution for an unpartitioned append-only table by copy-pasting config from a partitioned or upsert job; assuming hash mode is valid everywhere.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Hash distribute rows by equality fields, even though {}=rang
• ${tableName}: Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mod
• Unrecognized :
• Unrecognized write.distribution-mode:
• Unrecognized write.distribution-mode:

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