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 reads the version byte of a serialized split and dispatches to deserializeV1/V2/V3. Any other version (including 0 or versions from a newer Iceberg) throws an IOException stating the unsupported version and listing [1] (message text is slightly stale since 2 and 3 are also supported).

Source

Thrown at flink/v2.3/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. Restore the job with the same or newer iceberg-flink version that wrote the split state.
2. Set the serializer version consistently (IcebergSourceOptions.SPLIT_SERIALIZER_VERSION / simple vs versioned serializer) so writer and reader agree.
3. If downgrade is unavoidable, run the old job to completion or use a compatibility version that can read the existing split format.
4. Report/patch the stale '[1]' message if it misleads your debugging; versions 2 and 3 are supported.

// inspect first byte of serialized split before deserializing
int version = serialized[0];
if (version < 1 || version > 3) throw new IOException('split version ' + version + ' unreadable by this Iceberg version');

try { split = serializer.deserialize(version, bytes); } catch (IOException e) { if (e.getMessage().contains('unsupported version')) { throw new IllegalStateException('Restore with the Iceberg version that wrote the checkpoint', e); } throw e; }

When it happens

Trigger: A split serializer instance configured with an older SIMPLE_VERSION (deserialize path gated by version 1) reads bytes whose version byte is 2 or 3, or bytes written by a newer Iceberg with an unknown version, during checkpoint/split-state recovery.

Common situations: Downgrading iceberg-flink between job stop and restore; savepoints shared across clusters with different Iceberg versions; manually crafted/edited split bytes.

Related errors

• Unknown serialize version: ${version}
• Unrecognized version or corrupt state: ${version}
• Unrecognized version or corrupt state: ${version}
• Unrecognized version or corrupt state: <version>
• Unrecognized version or corrupt state: ${version}

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