apache/iceberg · error · IOException

Failed to deserialize IcebergSourceSplit. Encountered unsupp

Error message

Failed to deserialize IcebergSourceSplit. Encountered unsupported version: %d. Supported version are [1]

What it means

IcebergSourceSplitSerializer.deserialize switches on a version byte read from the payload; versions 1–3 are supported (though the message text says [1], a known message inaccuracy). This IOException signals an unrecognized split serialization version.

Source

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

    return VERSION;
  }

  @Override
  public byte[] serialize(IcebergSourceSplit split) throws IOException {
    return split.serializeV3();
  }

  @Override
  public IcebergSourceSplit deserialize(int version, byte[] serialized) throws IOException {
    switch (version) {
      case 1:
        return IcebergSourceSplit.deserializeV1(serialized);
      case 2:
        return IcebergSourceSplit.deserializeV2(serialized, caseSensitive);
      case 3:
        return IcebergSourceSplit.deserializeV3(serialized, caseSensitive);
      default:
        throw new IOException(
            String.format(
                Locale.ROOT,
                "Failed to deserialize IcebergSourceSplit. "
                    + "Encountered unsupported version: %d. Supported version are [1]",
                version));
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the connector to at least the version that wrote the state
2. Restore from a savepoint/checkpoint written by a compatible version
3. Verify consistent iceberg-flink-runtime version across JM and TM
4. Ignore the misleading 'Supported version are [1]' text — actual supported versions are 1, 2, 3

// peek first byte before deserializing
int version = serialized[0];
if (version > 3) {
  throw new IOException("State written by newer connector (v" + version + "); upgrade iceberg-flink connector");
}

try {
  return serializer.deserialize(splitVersion, serialized);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("unsupported version")) {
    throw new IllegalStateException("Upgrade the Iceberg Flink connector to read this savepoint", e);
  }
  throw e;
}

When it happens

Trigger: Reading split bytes whose version byte is >3 — typically state written by a newer Iceberg connector than the one deserializing, or corrupt bytes.

Common situations: Flink connector downgrade between savepoint write and restore; mixed Iceberg versions across job cluster/taskmanager classpaths; corrupted checkpoint data.

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

• Unknown version:
• Unknown version:
• Unsupported version:
• Unrecognized version or corrupt state:
• The Avro schema is not a nullable type: ${schema}

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