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

HashKeyGenerator.getKeySelector logs this warning when RANGE distribution mode is requested but no equality fields are set. Range distribution by partition key is not supported in the Flink sink, so with no equality fields there is nothing to range-assign on; the generator falls back to 'none' distribution mode via tableKeySelector.

Solutions

  1. Set equality fields so the sink can key records for distribution.
  2. Change write.distribution-mode to 'none' or 'hash' in the Flink sink configuration.
  3. Do range clustering upstream (e.g. sort/rewrite with Spark) instead of relying on Flink range distribution.

Example fix

// before
table property: write.distribution-mode=range  (Flink job, no equality fields)

// after
table property: write.distribution-mode=hash  + equalityFields=["id"]
// or write.distribution-mode=none
Defensive patterns

Strategy: validation

Validate before calling

if ("range".equals(writeDistributionMode) && equalityFields.isEmpty()) {
  throw new IllegalArgumentException(
      "Flink sink does not support range distribution without equality fields; use 'hash' or 'none'");
}

Prevention

When it happens

Trigger: DynamicRecord/sink config with WRITE_DISTRIBUTION_MODE='range' and an empty equalityFields set; the RANGE branch of getKeySelector warns and returns tableKeySelector instead of a range key selector.

Common situations: Migrating a Spark Iceberg writer configuration (which supports range distribution) to the Flink sink without adjusting write.distribution-mode; generic table properties like write.distribution-mode=range applied to Flink jobs.

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/1c1e21f51927efb0. Report an issue: GitHub.

Appendix: source

Thrown at flink/v2.1/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)