apache/iceberg · error · IllegalArgumentException

tableName + ": Unrecognized " + WRITE_DISTRIBUTION_MODE + ":

Error message

tableName + ": Unrecognized " + WRITE_DISTRIBUTION_MODE + ": " + mode

What it means

HashKeyGenerator.getKeySelector builds a key selector based on the table's write.distribution-mode. If the parsed mode is none of NONE, HASH, or RANGE (the recognized cases), the switch's default throws an IllegalArgumentException including the table name and the raw mode value.

Source

Thrown at flink/v2.3/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 one of: none, hash, range
2. Remove the property to fall back to the default mode
3. Upgrade the Flink Iceberg runtime to a version that supports the mode

Example fix

// before
table.properties().set(TableProperties.WRITE_DISTRIBUTION_MODE, "hashkey");
// after
table.properties().set(TableProperties.WRITE_DISTRIBUTION_MODE,
    TableProperties.WRITE_DISTRIBUTION_MODE_HASH);

String mode = table.properties().get(TableProperties.WRITE_DISTRIBUTION_MODE);
if (mode != null && !Set.of("none", "hash", "range").contains(mode)) {
  throw new IllegalArgumentException("Invalid write.distribution-mode: " + mode);
}

try {
  keySelector = HashKeyGenerator.keySelector(...);
} catch (IllegalArgumentException e) {
  // fall back to default distribution or fail fast with a clear message
}

When it happens

Trigger: Setting write.distribution-mode to an unrecognized string in table properties or sink configuration, or a mode enum value added in a newer Iceberg being read by an older sink.

Common situations: Typos in table properties (e.g. 'hashkey'), or using tables written by newer Iceberg versions that define new distribution modes.

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:
• : Unrecognized write.distribution-mode:

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