{"record":{"id":"4ef96d93c0f1abe9","repo":"apache/iceberg","slug":"tablename-unrecognized-write-distribution-mode","errorCode":null,"errorMessage":"${tableName}: Unrecognized write.distribution-mode: ${mode}","messagePattern":"(.+?): Unrecognized write\\.distribution-mode: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/sink/dynamic/HashKeyGenerator.java","lineNumber":194,"sourceCode":"        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);\n    }\n  }\n\n  private static KeySelector<RowData, Integer> equalityFieldKeySelector(\n      String tableName,\n      Schema schema,\n      Set<String> equalityFields,\n      int writeParallelism,\n      int maxWriteParallelism) {\n    return new TargetLimitedKeySelector(\n        new EqualityFieldKeySelector(\n            schema,\n            FlinkSchemaUtil.convert(schema),\n            DynamicSinkUtil.getEqualityFieldIds(equalityFields, schema)),\n        tableName,\n        writeParallelism,\n        maxWriteParallelism);","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/sink/dynamic/HashKeyGenerator.java#L176-L212","documentation":"HashKeyGenerator.getKeySelector maps a table's write.distribution-mode to a Flink KeySelector. The switch only handles NONE/HASH kinds of modes it supports; any other string value is rejected with this IllegalArgumentException. The mode comes from table properties, so an unexpected value means misconfiguration or an unparseable distribution mode.","triggerScenarios":"Calling keySelector() for a table whose write.distribution-mode property is set to an unrecognized value (e.g. typo, 'ring', or a mode added in a newer spec that this connector version does not know).","commonSituations":"Setting write.distribution-mode to an invalid string in table properties, using a newer Iceberg table mode value with an older Flink connector, or programmatic builds that pass a wrong DistributionMode name.","solutions":["Set write.distribution-mode to a supported value: none, hash, or range.","Remove the property to fall back to the connector default.","Upgrade the Iceberg Flink connector if the mode is valid but newer than the connector."],"exampleFix":"// before\nALTER TABLE t SET TBLPROPERTIES ('write.distribution-mode'='hashkey');\n// after\nALTER TABLE t SET TBLPROPERTIES ('write.distribution-mode'='hash');","handlingStrategy":"validation","validationCode":"String mode = table.properties().getOrDefault(\"write.distribution-mode\", \"none\");\nSet<String> allowed = Set.of(\"none\", \"hash\", \"range\");\nif (!allowed.contains(mode.toLowerCase(Locale.ROOT))) {\n  throw new IllegalArgumentException(\"Unsupported write.distribution-mode: \" + mode);\n}","typeGuard":null,"tryCatchPattern":"try {\n  keySelector = generator.keySelector(table, schema, ...);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"Unrecognized write.distribution-mode\")) {\n    keySelector = fallbackKeySelector;\n  } else throw e;\n}","preventionTips":["Only set write.distribution-mode to none, hash, or range.","Check table properties with DESCRIBE TABLE before running Flink writes.","Upgrade the connector when adopting table modes introduced in newer specs."],"tags":["flink","config","iceberg"],"backgroundTag":"invalid-enum-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}