{"record":{"id":"b4891adb31b6041b","repo":"apache/iceberg","slug":"unknown-version-version","errorCode":null,"errorMessage":"Unknown version: {version}","messagePattern":"Unknown version: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/source/enumerator/IcebergEnumeratorPositionSerializer.java","lineNumber":53,"sourceCode":"      ThreadLocal.withInitial(() -> new DataOutputSerializer(128));\n\n  @Override\n  public int getVersion() {\n    return VERSION;\n  }\n\n  @Override\n  public byte[] serialize(IcebergEnumeratorPosition position) throws IOException {\n    return serializeV1(position);\n  }\n\n  @Override\n  public IcebergEnumeratorPosition deserialize(int version, byte[] serialized) throws IOException {\n    switch (version) {\n      case 1:\n        return deserializeV1(serialized);\n      default:\n        throw new IOException(\"Unknown version: \" + version);\n    }\n  }\n\n  private byte[] serializeV1(IcebergEnumeratorPosition position) throws IOException {\n    DataOutputSerializer out = SERIALIZER_CACHE.get();\n    out.writeBoolean(position.snapshotId() != null);\n    if (position.snapshotId() != null) {\n      out.writeLong(position.snapshotId());\n    }\n    out.writeBoolean(position.snapshotTimestampMs() != null);\n    if (position.snapshotTimestampMs() != null) {\n      out.writeLong(position.snapshotTimestampMs());\n    }\n    byte[] result = out.getCopyOfBuffer();\n    out.clear();\n    return result;\n  }\n","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/source/enumerator/IcebergEnumeratorPositionSerializer.java#L35-L71","documentation":"IcebergEnumeratorPositionSerializer.deserialize throws IOException when the serialized enumerator position blob carries a version byte the deserializer doesn't know (only version 1 exists). This guards state compatibility: a position written by an incompatible writer cannot be safely read.","triggerScenarios":"Restoring a Flink job from a savepoint/checkpoint whose enumerator-state bytes were written by a different (newer) Iceberg connector version that bumped the serializer version.","commonSituations":"Upgrading the Iceberg flink-runtime jar while resuming from an old savepoint; downgrading the connector and feeding it state written by a newer version.","solutions":["Resume with the same (or newer) Iceberg connector version that wrote the savepoint.","If a downgrade is required, start a new job without state instead of restoring incompatible enumerator state.","If both versions are known-compatible, allow state rescaling/restart with a compatible serializer or drop operator state via the upgrade mode.","Migrate state by writing a custom state-processor job that rewrites the position to the supported version."],"exampleFix":"// before: downgrade then restore\nflink-runtime: 1.9.0 (writes version 2) -> restore with 1.6.0 (knows only 1)\n// after: restore with matching version\nflink savepoint run with 1.6.0 restored using iceberg-flink-runtime 1.6.x","handlingStrategy":"try-catch","validationCode":"// resume with the exact connector version that wrote the savepoint\nString stateVersion = // read version byte from checkpoint metadata if inspectable\nif (!expectedConnectorVersion.equals(writingConnectorVersion)) {\n  throw new IllegalStateException(\"Restore requires connector \" + writingConnectorVersion);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never downgrade the connector across a savepoint restore.","Keep the iceberg-flink-runtime artifact identical in all environments.","Plan upgrades with savepoint compatibility tests."],"tags":["flink","serialization","state","version-mismatch"],"backgroundTag":"incompatible-source-type","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}