: 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

HashKeyGenerator.getKeySelector warns that a hash distribution request is degraded to 'none' mode (per-table fan-out via tableKeySelector) when there are no equality fields and the table is unpartitioned, since there is no key to hash. Rows are therefore not clustered by any key before writing.

Solutions

Add a partition spec or identifier fields (primary keys) to the affected table so hash keying is possible.
Change the job/table write.distribution-mode to 'none' for key-less unpartitioned tables.
Verify equalityFields resolution in the dynamic sink config for that table name.

Example fix

// before
--table-props write.distribution-mode=hash // applies to unpartitioned, key-less table too
// after
// per-table: set write.distribution-mode=none for tables without partition spec / primary keys

Defensive patterns

Strategy: validation

Validate before calling

if (mode == DistributionMode.HASH && equalityFields.isEmpty() && spec.isUnpartitioned()) {
  LOG.warn("{}: hash mode degraded to none", tableName); // surface before submit
}

Prevention

Audit dynamic-sink target tables for missing partition specs / primary keys
Set per-table write.distribution-mode appropriately in dynamic pipelines
Alert on the per-table warning to catch schema drift in multi-table streams

When it happens

Trigger: Dynamic Iceberg sink processing a table with HASH distribution mode, empty equalityFields, and an unpartitioned spec; the tableName is included in the message to identify which table in the dynamic stream is affected.

Common situations: Dynamic multi-table pipelines where some target tables lack partition specs and primary keys while the job is configured with hash distribution; schema changes removing identifier fields from a table.

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

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

Appendix: source

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