apache/iceberg · error · IllegalArgumentException

${tableName}: Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mod

Error message

${tableName}: Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mode}

What it means

The dynamic Flink sink builds a key selector based on the table's write.distribution-mode property. When the mode string read from table properties is not one of the recognized values (none/hash), getKeySelector throws IllegalArgumentException naming the table and the offending mode. This guards against misconfigured or future/unsupported distribution modes reaching the sink's hashing path.

Source

Thrown at flink/v1.20/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. Change the table property write.distribution-mode to a supported value (none or hash): ALTER TABLE ... SET TBLPROPERTIES ('write.distribution-mode'='hash')
2. If range distribution is intended, use the regular (non-dynamic) Iceberg Flink sink that supports RANGE mode, or pre-partition the data yourself
3. Check for typos in the mode value; values are matched literally after normalization, e.g. use 'hash' not 'HASHED'
4. Verify which table is named in the message and inspect its properties via the catalog before restarting the job

Example fix

// before (table properties)
'write.distribution-mode'='range'
// after
'write.distribution-mode'='hash'

String mode = table.properties().getOrDefault(TableProperties.WRITE_DISTRIBUTION_MODE_DEFAULT, TableProperties.WRITE_DISTRIBUTION_MODE_NONE);
if (!mode.equals(TableProperties.WRITE_DISTRIBUTION_MODE_NONE) && !mode.equals(TableProperties.WRITE_DISTRIBUTION_MODE_HASH)) {
  throw new IllegalArgumentException("Unsupported write.distribution-mode for dynamic sink: " + mode);
}

When it happens

Trigger: A table's WRITE_DISTRIBUTION_MODE property contains a value other than none or hash (e.g. 'range' or a typo like 'hsh') when the dynamic sink's HashKeyGenerator.getKeySelector creates the key selector for that table.

Common situations: Setting write.distribution-mode=range in table properties while using the Flink dynamic sink which only supports none/hash for equality-field keying; manual property edits with typos; writing to a table whose properties were created by a newer engine version with an unrecognized mode value.

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

• Unrecognized :
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${writeMode}
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mode}
• Unknown file format %s
• ${tableName}: Unrecognized write.distribution-mode: ${mode}

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