{"record":{"id":"c158eabaa69eb424","repo":"apache/iceberg","slug":"fallback-to-use-none-distribution-mode-because-c158ea","errorCode":null,"errorMessage":"Fallback to use 'none' distribution mode, because there are no equality fields set and table is unpartitioned","messagePattern":"Fallback to use 'none' distribution mode, because there are no equality fields set and table is unpartitioned","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java","lineNumber":1001,"sourceCode":"        throw new RuntimeException(\"Unrecognized \" + WRITE_DISTRIBUTION_MODE + \": \" + mode);\n    }\n  }\n\n  private DataStream<RowData> distributeDataStreamByNoneDistributionMode(\n      DataStream<RowData> input, Schema iSchema) {\n    if (equalityFieldIds.isEmpty()) {\n      return input;\n    } else {\n      LOG.info(\"Distribute rows by equality fields, because there are equality fields set\");\n      return input.keyBy(new EqualityFieldKeySelector(iSchema, flinkRowType, equalityFieldIds));\n    }\n  }\n\n  private DataStream<RowData> distributeDataStreamByHashDistributionMode(\n      DataStream<RowData> input, Schema iSchema, PartitionSpec partitionSpec) {\n    if (equalityFieldIds.isEmpty()) {\n      if (partitionSpec.isUnpartitioned()) {\n        LOG.warn(\n            \"Fallback to use 'none' distribution mode, because there are no equality fields set \"\n                + \"and table is unpartitioned\");\n        return input;\n      } else {\n        return input.keyBy(new PartitionKeySelector(partitionSpec, iSchema, flinkRowType));\n      }\n    } else {\n      if (partitionSpec.isUnpartitioned()) {\n        LOG.info(\n            \"Distribute rows by equality fields, because there are equality fields set \"\n                + \"and table is unpartitioned\");\n        return input.keyBy(new EqualityFieldKeySelector(iSchema, flinkRowType, equalityFieldIds));\n      } else {\n        for (PartitionField partitionField : partitionSpec.fields()) {\n          Preconditions.checkState(\n              equalityFieldIds.contains(partitionField.sourceId()),\n              \"In 'hash' distribution mode with equality fields set, source column '%s' of partition field '%s' \"\n                  + \"should be included in equality fields: '%s'\",","sourceCodeStart":983,"sourceCodeEnd":1019,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergSink.java#L983-L1019","documentation":"When 'hash' write distribution mode is requested but the sink has no equality fields configured and the target table is unpartitioned, there is no key to hash by. The sink warns and falls back to 'none' distribution, sending rows to writers round-robin instead of keying the DataStream.","triggerScenarios":"Building an IcebergSink with DistributionMode.HASH (or write.distribution-mode=hash) on an unpartitioned table while equalityFieldIds is empty.","commonSituations":"Configuring hash distribution for an unpartitioned append-only table by copy-pasting config from a partitioned or upsert job; assuming hash mode is valid everywhere.","solutions":["Remove the hash distribution setting for the unpartitioned table ('none' is appropriate for append-only unpartitioned writes).","If upsert semantics are needed, set .equalityFields(...) / equality field ids so hash distribution has keys.","Switch to partitioned writes if hashing by partition key is intended."],"exampleFix":"// before\nFlinkSink.forRowData(input)\n    .table(unpartitionedTable)\n    .distributionMode(DistributionMode.HASH)\n    .append();\n// after\nFlinkSink.forRowData(input)\n    .table(unpartitionedTable)\n    .distributionMode(DistributionMode.NONE)\n    .append();","handlingStrategy":"validation","validationCode":"if (distMode == DistributionMode.HASH && table.spec().isUnpartitioned()\n    && (equalityFields == null || equalityFields.isEmpty())) {\n  LOG.warn(\"HASH distribution is meaningless here; use NONE or add equality fields/partitioning\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Match distribution mode to table partitioning and equality fields.","Don't copy distribution config between append and upsert jobs."],"tags":["flink","iceberg-sink","distribution-mode"],"backgroundTag":"invalid-config-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}