{"record":{"id":"33c1c6544c09b2c2","repo":"apache/iceberg","slug":"tablename-unrecognized-write-distribution","errorCode":null,"errorMessage":"tableName + \": Unrecognized \" + WRITE_DISTRIBUTION_MODE + \": \" + mode","messagePattern":"tableName \\+ \": Unrecognized \" \\+ WRITE_DISTRIBUTION_MODE \\+ \": \" \\+ mode","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink/v2.3/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.3/flink/src/main/java/org/apache/iceberg/flink/sink/dynamic/HashKeyGenerator.java#L176-L212","documentation":"HashKeyGenerator.getKeySelector builds a key selector based on the table's write.distribution-mode. If the parsed mode is none of NONE, HASH, or RANGE (the recognized cases), the switch's default throws an IllegalArgumentException including the table name and the raw mode value.","triggerScenarios":"Setting write.distribution-mode to an unrecognized string in table properties or sink configuration, or a mode enum value added in a newer Iceberg being read by an older sink.","commonSituations":"Typos in table properties (e.g. 'hashkey'), or using tables written by newer Iceberg versions that define new distribution modes.","solutions":["Set write.distribution-mode to one of: none, hash, range","Remove the property to fall back to the default mode","Upgrade the Flink Iceberg runtime to a version that supports the mode"],"exampleFix":"// before\ntable.properties().set(TableProperties.WRITE_DISTRIBUTION_MODE, \"hashkey\");\n// after\ntable.properties().set(TableProperties.WRITE_DISTRIBUTION_MODE,\n    TableProperties.WRITE_DISTRIBUTION_MODE_HASH);","handlingStrategy":"validation","validationCode":"String mode = table.properties().get(TableProperties.WRITE_DISTRIBUTION_MODE);\nif (mode != null && !Set.of(\"none\", \"hash\", \"range\").contains(mode)) {\n  throw new IllegalArgumentException(\"Invalid write.distribution-mode: \" + mode);\n}","typeGuard":null,"tryCatchPattern":"try {\n  keySelector = HashKeyGenerator.keySelector(...);\n} catch (IllegalArgumentException e) {\n  // fall back to default distribution or fail fast with a clear message\n}","preventionTips":["Use TableProperties.WRITE_DISTRIBUTION_MODE_* constants, not raw strings","Validate table properties before submitting the Flink job","Upgrade runtime when tables use newer distribution modes"],"tags":["flink","config","distribution-mode"],"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-14T21:17:11.552Z"}