apache/iceberg · error · RuntimeException

Unrecognized :

Error message

Unrecognized : 

What it means

When building the sink, FlinkSink.distributeDataStream() applies a distribution transformation keyed by the table's write.distribution-mode (NONE/HASH). A writeMode value outside the supported set (e.g. an unrecognized string or a future mode like RANGE in a build lacking support) hits the default branch and throws RuntimeException.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/sink/FlinkSink.java:721

            shuffleStream = shuffleStream.uid(uidPrefix + "-shuffle");
          }

          return shuffleStream
              .partitionCustom(new RangePartitioner(iSchema, sortOrder), r -> r)
              .flatMap(
                  (FlatMapFunction<StatisticsOrRecord, RowData>)
                      (statisticsOrRecord, out) -> {
                        if (statisticsOrRecord.hasRecord()) {
                          out.collect(statisticsOrRecord.record());
                        }
                      })
              // Set the parallelism same as writerParallelism to
              // promote operator chaining with the downstream writer operator
              .setParallelism(writerParallelism)
              .returns(RowData.class);

        default:
          throw new RuntimeException("Unrecognized " + WRITE_DISTRIBUTION_MODE + ": " + writeMode);
      }
    }
  }

  /**
   * Clean up after removing {@link Builder#tableSchema}
   *
   * @deprecated since 1.10.0, will be removed in 2.0.0. Use {@link #toFlinkRowType(Schema,
   *     ResolvedSchema)} instead.
   */
  @Deprecated
  static RowType toFlinkRowType(Schema schema, TableSchema requestedSchema) {
    if (requestedSchema != null) {
      // Convert the flink schema to iceberg schema using the table schema as the reference.
      Schema writeSchema = FlinkSchemaUtil.convert(schema, requestedSchema);
      TypeUtil.validateWriteSchema(schema, writeSchema, true, true);

      // We use this flink schema to read values from RowData. The flink's TINYINT and SMALLINT will

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set write.distribution-mode to a supported value: none or hash (for this code path).
2. Correct typos/whitespace in the table property: ALTER TABLE ... SET TBLPROPERTIES ('write.distribution-mode'='hash').
3. Remove the property entirely to fall back to the default behavior if no specific distribution is needed.
4. Upgrade Iceberg if a newer distribution mode (e.g. range) support is required for Flink.

Example fix

// before
ALTER TABLE t SET TBLPROPERTIES ('write.distribution-mode'='range');
// after
ALTER TABLE t SET TBLPROPERTIES ('write.distribution-mode'='hash');

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

try { buildSink(); } catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains(WRITE_DISTRIBUTION_MODE)) {
    LOG.error("Fix write.distribution-mode table property", e);
  }
}

When it happens

Trigger: Setting table property write.distribution-mode to an unsupported/typo'd value (e.g. 'range' with a build that doesn't support it, or 'hash ' with stray characters) before constructing FlinkSink with keyed output.

Common situations: Hand-editing table properties; copying distribution-mode settings from Spark docs into a Flink table where only none/hash are handled; case/format mistakes like NONE vs none depending on parse path.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• ${tableName}: Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mod
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${writeMode}
• Unrecognized ${WRITE_DISTRIBUTION_MODE}: ${mode}
• Unknown file format %s
• Failed to load iceberg table from table loader:

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