apache/iceberg · error · IllegalArgumentException

: Unrecognized write.distribution-mode:

Error message

: Unrecognized write.distribution-mode: 

What it means

HashKeyGenerator.getKeySelector switches on the table's write.distribution-mode. Only NONE/HASH (and equality-field modes handled by earlier branches) are supported; any other value falls to default and throws IllegalArgumentException with the table name, property name, and offending mode value.

Source

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

        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);
    }
  }

  private static KeySelector<RowData, Integer> equalityFieldKeySelector(
      String tableName,
      Schema schema,
      Set<String> equalityFields,
      int writeParallelism,
      int maxWriteParallelism) {
    return new TargetLimitedKeySelector(
        new EqualityFieldKeySelector(
            schema,
            FlinkSchemaUtil.convert(schema),
            DynamicSinkUtil.getEqualityFieldIds(equalityFields, schema)),
        tableName,
        writeParallelism,
        maxWriteParallelism);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set write.distribution-mode to 'none' or 'hash' on the table.
2. If you need range distribution, pre-partition upstream or drop the property so the sink picks its default.
3. Fix typos in the property value; values are matched case-sensitively via DistributionMode parsing.

Example fix

// before
table.updateProperties().set(TableProperties.WRITE_DISTRIBUTION_MODE, "range").commit();
// after
table.updateProperties().set(TableProperties.WRITE_DISTRIBUTION_MODE, "hash").commit();

String mode = table.properties().getOrDefault(TableProperties.WRITE_DISTRIBUTION_MODE, TableProperties.WRITE_DISTRIBUTION_MODE_NONE); if (!mode.equalsIgnoreCase("none") && !mode.equalsIgnoreCase("hash")) { throw new IllegalArgumentException("Unsupported write.distribution-mode for Flink: " + mode); }

try { keySelector = HashKeyGenerator.getKeySelector(...); } catch (IllegalArgumentException e) { /* reset the table property to none/hash and retry */ throw e; }

When it happens

Trigger: Setting write.distribution-mode to a value other than none/hash (e.g. a typo like 'hase' or an unsupported 'range' in this Flink dynamic sink path) and building a key selector for the writer.

Common situations: Table properties copied from Spark (where 'range' is valid) but consumed by the Flink dynamic sink; hand-edited table properties with typos.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• ${tableName}: Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mod
• Unrecognized :
• Unrecognized write.distribution-mode:
• Unrecognized write.distribution-mode:
• tableName + ": Unrecognized " + WRITE_DISTRIBUTION_MODE + ":

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