apache/iceberg · warning

: Fallback to use 'none' distribution mode, because there…

Error message

{}: Fallback to use 'none' distribution mode, because there are no equality fields set and {}='range' is not supported yet in flink

What it means

This is a warning logged by HashKeyGenerator when a table's write distribution mode is 'range' but no equality fields are configured. Flink does not yet support range distribution for keyed writes, so the writer silently falls back to 'none' distribution mode, meaning records are not distributed by key and may be less evenly balanced across subtasks.

Solutions

  1. Set equality fields on the table (schema or write properties) so range distribution is not attempted without them
  2. Change the write distribution mode to 'hash' or 'none' via WRITE_DISTRIBUTION_MODE property
  3. If 'none' distribution is acceptable, ignore the warning but be aware of potential data skew

Example fix

// before
table.property(WRITE_DISTRIBUTION_MODE, "range"); // no equality fields
// after
table.property(WRITE_DISTRIBUTION_MODE, "hash");
// or configure equality fields
table.property(WRITE_DISTRIBUTION_MODE, "range"); // + equality-fields configured
Defensive patterns

Strategy: validation

Validate before calling

if ("range".equals(table.properties().getOrDefault(TableProperties.WRITE_DISTRIBUTION_MODE, "none"))
    && (equalityFields == null || equalityFields.isEmpty())) {
  // either set equality fields or switch to hash/none
}

Prevention

When it happens

Trigger: Writing to a table with WRITE_DISTRIBUTION_MODE='range' via the Flink dynamic sink when the table (or write conf) has no equality fields set; the RANGE case in getKeySelector is entered with equalityFields.isEmpty().

Common situations: Users migrating Spark jobs that use range distribution to Flink; setting write.distribution-mode=range on an unpartitioned/non-equality-field table expecting Spark-like behavior.

Related errors

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

Appendix: source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/sink/dynamic/HashKeyGenerator.java:177

              Types.NestedField sourceField = schema.findField(partitionField.sourceId());
              Preconditions.checkState(
                  sourceField != null && equalityFields.contains(sourceField.name()),
                  "%s: In 'hash' distribution mode with equality fields set, partition field '%s' "
                      + "should be included in equality fields: '%s'",
                  tableName,
                  partitionField,
                  schema.columns().stream()
                      .filter(c -> equalityFields.contains(c.name()))
                      .collect(Collectors.toList()));
            }
            return partitionKeySelector(
                tableName, schema, spec, writeParallelism, maxWriteParallelism);
          }
        }

      case RANGE:
        if (equalityFields.isEmpty()) {
          LOG.warn(
              "{}: Fallback to use 'none' distribution mode, because there are no equality fields set "
                  + "and {}='range' is not supported yet in flink",
              tableName,
              WRITE_DISTRIBUTION_MODE);
          return tableKeySelector(tableName, writeParallelism, maxWriteParallelism);
        } else {
          LOG.info(
              "{}: Distribute rows by equality fields, because there are equality fields set "
                  + "and {}='range' is not supported yet in flink",
              tableName,
              WRITE_DISTRIBUTION_MODE);
          return equalityFieldKeySelector(
              tableName, schema, equalityFields, writeParallelism, maxWriteParallelism);
        }

      default:
        throw new IllegalArgumentException(
            tableName + ": Unrecognized " + WRITE_DISTRIBUTION_MODE + ": " + mode);

View on GitHub (pinned to 86d9c8fc54)