apache/iceberg · error · IllegalArgumentException

Unsupported version:

Error message

Unsupported version: 

What it means

IcebergSourceSplit.writeTaskJson serializes the TableScan task JSON differently per version (2 = writeUTF, 3 = writeLongUTF for large payloads). This IllegalArgumentException is thrown for any other version value.

Source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplit.java:179

      serializedBytesCache = out.getCopyOfBuffer();
      out.clear();
    }

    return serializedBytesCache;
  }

  private static void writeTaskJson(DataOutputSerializer out, String taskJson, int version)
      throws IOException {
    switch (version) {
      case 2:
        out.writeUTF(taskJson);
        break;
      case 3:
        SerializerHelper.writeLongUTF(out, taskJson);
        break;
      default:
        throw new IllegalArgumentException("Unsupported version: " + version);
    }
  }

  static IcebergSourceSplit deserializeV2(byte[] serialized, boolean caseSensitive)
      throws IOException {
    return deserialize(serialized, caseSensitive, 2);
  }

  static IcebergSourceSplit deserializeV3(byte[] serialized, boolean caseSensitive)
      throws IOException {
    return deserialize(serialized, caseSensitive, 3);
  }

  private static IcebergSourceSplit deserialize(
      byte[] serialized, boolean caseSensitive, int version) throws IOException {
    DataInputDeserializer in = new DataInputDeserializer(serialized);
    int fileOffset = in.readInt();
    long recordOffset = in.readLong();

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Only use serialize(2) or serialize(3) (serializeV2/serializeV3 helpers)
2. Use the public IcebergSourceSplitSerializer instead of calling writeTaskJson directly
3. Fix any hardcoded version constant to 2 or 3

Example fix

// before
byte[] bytes = split.serialize(4);
// after
byte[] bytes = split.serializeV3();

// only call supported versions
if (version != 2 && version != 3) {
  throw new IllegalArgumentException("Use serializeV2()/serializeV3() only");
}

try {
  byte[] bytes = split.serializeV3();
} catch (IllegalArgumentException e) {
  LOG.error("Unsupported split serialization version requested", e);
  throw e;
}

When it happens

Trigger: An internal/programmatic call to serialize with a version other than 2 or 3 (serialize(1) goes through a different Java-serialization path; anything else hits this).

Common situations: Custom fork or test code calling serialize/writeTaskJson with a wrong version constant; version constant typos.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unsupported version:
• Unknown version:
• Failed to deserialize IcebergSourceSplit. Encountered unsupp
• The Avro schema is not a nullable type: ${schema}
• Fail to serialize at field: %s.

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