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 WRITE_DISTRIBUTION_MODE=hash is requested but the sink has no equality fields and the table is unpartitioned, there is no key to hash by, so FlinkSink silently falls back to the 'none' (no shuffle) distribution and logs this warning. Rows will not be clustered by any key.

Solutions

Remove write.distribution-mode=hash or set it to none for this table.
Add a partition spec to the table if clustering by partition is desired.
Configure equalityFieldColumns if the table actually has a logical key to hash by.

Example fix

// before
table.updateProperties().set(TableProperties.WRITE_DISTRIBUTION_MODE, "hash").commit(); // unpartitioned table
// after
table.updateProperties().set(TableProperties.WRITE_DISTRIBUTION_MODE, "none").commit();

Defensive patterns

Strategy: validation

Validate before calling

if (mode == DistributionMode.HASH && eqFieldIds.isEmpty() && table.spec().isUnpartitioned()) {
  mode = DistributionMode.NONE; // avoid the silent fallback
}

Prevention

Only set write.distribution-mode=hash on partitioned or key-ed tables
Check table.spec().isUnpartitioned() before choosing a distribution mode
Centralize distribution-mode selection logic in one helper

When it happens

Trigger: distributeDataStream with DistributionMode.HASH, equalityFieldIds empty, and partitionSpec.isUnpartitioned() true — e.g. setting write.distribution-mode=hash on an unpartitioned table without primary keys.

Common situations: Copy-pasting sink config with write.distribution-mode=hash onto an unpartitioned, key-less table; expecting hash mode to reduce small files when no partition or key exists.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/sink/FlinkSink.java:634

      Schema iSchema = table.schema();
      PartitionSpec partitionSpec = table.spec();
      SortOrder sortOrder = table.sortOrder();

      switch (writeMode) {
        case NONE:
          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));
          }

        case HASH:
          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' "

View on GitHub (pinned to 86d9c8fc54)