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's HASH distribution mode, rows are keyed by equality fields (upsert) or partition key. With no equality fields configured and an unpartitioned table there is nothing to hash by, so the sink logs this warning and falls back to 'none' distribution, sending rows as-is.

Source

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

Solutions

1. Use distribution mode 'none' explicitly for unpartitioned append-only tables
2. Partition the table so HASH mode can key by partition
3. Set equality fields (primary key) if writing upserts
4. Remove the hash distribution setting if no key exists

Example fix

// before
FlinkSink.forRowData(input).distributionMode(DistributionMode.HASH)...
// after
FlinkSink.forRowData(input).distributionMode(DistributionMode.NONE)...

if (distributionMode == DistributionMode.HASH
    && equalityFieldIds.isEmpty()
    && table.spec().isUnpartitioned()) {
  // no key exists; request NONE explicitly or add partitions/PK
  distributionMode = DistributionMode.NONE;
}

When it happens

Trigger: Builder has distribution mode HASH (or WRITE_DISTRIBUTION_MODE default resolves to it in streaming) while equalityFieldIds is empty and partitionSpec.isUnpartitioned() in distributeDataStream.

Common situations: Writing append-only data to an unpartitioned table with distribution-mode=hash configured; default streaming writes where users assumed hash is safe without a partition or PK.

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

• Fallback to use 'none' distribution mode, because there are
• Class %s does not implement DynamicRecordGeneratorSQL
• Failed to instantiate DynamicRecordGeneratorSQL %s
• Fallback to use 'none' distribution mode, because there are
• Hash distribute rows by equality fields, even though {}=rang

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