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

Error message

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

What it means

In the dynamic sink's HashKeyGenerator.getKeySelector, a HASH distribution mode was requested but the job specified no equality fields and the table is unpartitioned, so there is no key to hash by. The generator logs this warning and falls back to a 'none' distribution mode key selector (round-robin/broadcast to write parallelism), i.e. records will not be clustered by key.

Solutions

Set equality fields on the dynamic sink config so HASH mode has a key to distribute by.
Set the distribution mode to 'none' explicitly (or drop it) to acknowledge round-robin distribution.
Partition the table if key-based clustering is required, then rely on partition key selector.

Example fix

// before
DynamicSinkConfiguration: write-distribution-mode=hash, equalityFields=[] (unpartitioned table)

// after
DynamicSinkConfiguration: write-distribution-mode=hash, equalityFields=["id"]
// or
DynamicSinkConfiguration: write-distribution-mode=none

Defensive patterns

Strategy: validation

Validate before calling

if ("hash".equals(distributionMode) && equalityFields.isEmpty() && table.spec().isUnpartitioned()) {
  throw new IllegalArgumentException(
      "write.distribution-mode=hash requires equality fields on an unpartitioned table");
}

Prevention

Only request hash distribution when equality fields or partition keys exist.
Centralize distribution-mode configuration validation before job submission.
Prefer explicit 'none' when key-based clustering is not required.

When it happens

Trigger: DynamicRecord/DynamicSink configuration with WRITE_DISTRIBUTION_MODE='hash' while equalityFields is empty and PartitionSpec.isUnpartitioned() is true; getKeySelector then returns tableKeySelector instead of an equality/partition key selector.

Common situations: Setting write.distribution-mode=hash on an unpartitioned table without defining equality fields for upserts; copying sink options from a partitioned table config to an unpartitioned one.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

      int writeParallelism) {
    LOG.debug(
        "Creating new KeySelector for table '{}' with distribution mode '{}'", tableName, mode);
    switch (mode) {
      case NONE:
        if (equalityFields.isEmpty()) {
          return tableKeySelector(tableName, writeParallelism, maxWriteParallelism);
        } else {
          LOG.info(
              "{}: Distribute rows by equality fields, because there are equality fields set",
              tableName);
          return equalityFieldKeySelector(
              tableName, schema, equalityFields, writeParallelism, maxWriteParallelism);
        }

      case HASH:
        if (equalityFields.isEmpty()) {
          if (spec.isUnpartitioned()) {
            LOG.warn(
                "{}: Fallback to use 'none' distribution mode, because there are no equality fields set "
                    + "and table is unpartitioned",
                tableName);
            return tableKeySelector(tableName, writeParallelism, maxWriteParallelism);
          } else {
            return partitionKeySelector(
                tableName, schema, spec, writeParallelism, maxWriteParallelism);
          }
        } else {
          if (spec.isUnpartitioned()) {
            LOG.info(
                "{}: Distribute rows by equality fields, because there are equality fields set "
                    + "and table is unpartitioned",
                tableName);
            return equalityFieldKeySelector(
                tableName, schema, equalityFields, writeParallelism, maxWriteParallelism);
          } else {
            for (PartitionField partitionField : spec.fields()) {

View on GitHub (pinned to 86d9c8fc54)