{"record":{"id":"23ca3ad6b0bb29ce","repo":"apache/iceberg","slug":"fallback-to-use-none-distribution-mode-beca-23ca3a","errorCode":null,"errorMessage":"{}: Fallback to use 'none' distribution mode, because there are no equality fields set and {}='range' is not supported yet in flink","messagePattern":"(.+?): Fallback to use 'none' distribution mode, because there are no equality fields set and (.+?)='range' is not supported yet in flink","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/sink/dynamic/HashKeyGenerator.java","lineNumber":177,"sourceCode":"              Types.NestedField sourceField = schema.findField(partitionField.sourceId());\n              Preconditions.checkState(\n                  sourceField != null && equalityFields.contains(sourceField.name()),\n                  \"%s: In 'hash' distribution mode with equality fields set, partition field '%s' \"\n                      + \"should be included in equality fields: '%s'\",\n                  tableName,\n                  partitionField,\n                  schema.columns().stream()\n                      .filter(c -> equalityFields.contains(c.name()))\n                      .collect(Collectors.toList()));\n            }\n            return partitionKeySelector(\n                tableName, schema, spec, writeParallelism, maxWriteParallelism);\n          }\n        }\n\n      case RANGE:\n        if (equalityFields.isEmpty()) {\n          LOG.warn(\n              \"{}: Fallback to use 'none' distribution mode, because there are no equality fields set \"\n                  + \"and {}='range' is not supported yet in flink\",\n              tableName,\n              WRITE_DISTRIBUTION_MODE);\n          return tableKeySelector(tableName, writeParallelism, maxWriteParallelism);\n        } else {\n          LOG.info(\n              \"{}: Distribute rows by equality fields, because there are equality fields set \"\n                  + \"and {}='range' is not supported yet in flink\",\n              tableName,\n              WRITE_DISTRIBUTION_MODE);\n          return equalityFieldKeySelector(\n              tableName, schema, equalityFields, writeParallelism, maxWriteParallelism);\n        }\n\n      default:\n        throw new IllegalArgumentException(\n            tableName + \": Unrecognized \" + WRITE_DISTRIBUTION_MODE + \": \" + mode);","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/sink/dynamic/HashKeyGenerator.java#L159-L195","documentation":"This is a warning logged by HashKeyGenerator when a table's write distribution mode is 'range' but no equality fields are configured. Flink does not yet support range distribution for keyed writes, so the writer silently falls back to 'none' distribution mode, meaning records are not distributed by key and may be less evenly balanced across subtasks.","triggerScenarios":"Writing to a table with WRITE_DISTRIBUTION_MODE='range' via the Flink dynamic sink when the table (or write conf) has no equality fields set; the RANGE case in getKeySelector is entered with equalityFields.isEmpty().","commonSituations":"Users migrating Spark jobs that use range distribution to Flink; setting write.distribution-mode=range on an unpartitioned/non-equality-field table expecting Spark-like behavior.","solutions":["Set equality fields on the table (schema or write properties) so range distribution is not attempted without them","Change the write distribution mode to 'hash' or 'none' via WRITE_DISTRIBUTION_MODE property","If 'none' distribution is acceptable, ignore the warning but be aware of potential data skew"],"exampleFix":"// before\ntable.property(WRITE_DISTRIBUTION_MODE, \"range\"); // no equality fields\n// after\ntable.property(WRITE_DISTRIBUTION_MODE, \"hash\");\n// or configure equality fields\ntable.property(WRITE_DISTRIBUTION_MODE, \"range\"); // + equality-fields configured","handlingStrategy":"validation","validationCode":"if (\"range\".equals(table.properties().getOrDefault(TableProperties.WRITE_DISTRIBUTION_MODE, \"none\"))\n    && (equalityFields == null || equalityFields.isEmpty())) {\n  // either set equality fields or switch to hash/none\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use range distribution when equality fields are configured","Prefer 'hash' distribution for keyed Flink writes","Monitor logs for the fallback warning after changing distribution mode"],"tags":["flink","distribution-mode","configuration","fallback"],"backgroundTag":"unsupported-config-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}