apache/iceberg · error · IllegalArgumentException

Unsupported version: {version}

Error message

Unsupported version: {version}

What it means

IcebergSourceSplit.writeTaskJson serializes the embedded scan-task JSON with a per-version encoding (2: writeUTF, 3: SerializerHelper.writeLongUTF for strings longer than 64KB); any other version is rejected with IllegalArgumentException. It is an internal format guard on the split's binary layout.

Source

Thrown at flink/v2.1/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. Use the public entry points serializeV2()/serialize(3) rather than calling writeTaskJson directly.
2. Ensure any custom version bump updates writeTaskJson, readTaskJson, and the dispatch switch consistently.
3. Check merged backports/patches for mismatched version constants in IcebergSourceSplit.
4. Replace the split bytes and let the source re-serialize from a freshly planned scan if state is already corrupted.

Example fix

// before
split.writeTaskJson(out, json, 5); // unknown version
// after
split.writeTaskJson(out, json, 3); // long-UTF safe encoding

// only pass known versions
if (version != 2 && version != 3) {
  throw new IllegalArgumentException("writeTaskJson requires version 2 or 3, got " + version);
}

When it happens

Trigger: serialize() is called with a version other than 2 or 3 — only possible from code paths passing a hard-coded unsupported version, or a caller invoking internal serialization with a hand-chosen version.

Common situations: Custom code or tests calling the internal serialize/writeTaskJson with an invented version; backport patches that bumped version constants inconsistently between writeTaskJson and readTaskJson.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unknown version:
• Unknown version:
• Unsupported version:
• Unknown version: {version}
• Unknown version: {version}

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