apache/iceberg · info

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

In FlinkSink.distributeDataStream(), HASH distribution with no equality fields on an unpartitioned table has nothing meaningful to key by, so it logs this warning and returns the input unchanged — effectively falling back to NONE distribution. Rows are written without keying, which is fine for appends but changes expected shuffle behavior.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/sink/FlinkSink.java:632

      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)

Solutions

1. Set write.distribution-mode=none in the table properties or via FlinkOptions to make the behavior explicit
2. Add equality-field-columns if keyed distribution is actually required
3. Partition the table if hash distribution by partition key is desired
4. Ignore the warning if unkeyed append is intended
5. Verify job config matches the current table layout after table evolution

Example fix

// before (table property)
"write.distribution-mode" = "hash"  // unpartitioned table, no equality fields
// after
ALTER TABLE db.tbl SET TBLPROPERTIES ('write.distribution-mode'='none');

if ("hash".equals(table.properties().get("write.distribution-mode"))
    && table.spec().isUnpartitioned()
    && equalityFieldColumns.isEmpty()) {
  // set mode=none explicitly or add equality fields
}

When it happens

Trigger: write.distribution-mode=hash configured (or defaulted by upsert mode) while equalityFieldIds is empty AND the table partition spec is unpartitioned. Typical with equality-field-columns not set on an append job over an unpartitioned table.

Common situations: Setting distribution-mode=hash globally for a job writing to unpartitioned tables; upsert-related defaults applied but equality fields removed; table migrated from partitioned to unpartitioned while job config stayed fixed.

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

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

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