{"record":{"id":"9b6e8560fa5999b0","repo":"apache/pulsar","slug":"unknown-checkpoint-type-type","errorCode":null,"errorMessage":"Unknown checkpoint type: ${type}","messagePattern":"Unknown checkpoint type: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/CheckpointV5.java","lineNumber":101,"sourceCode":"        byte type = buf.get();\n\n        return switch (type) {\n            case TYPE_EARLIEST -> EARLIEST;\n            case TYPE_LATEST -> LATEST;\n            case TYPE_REGULAR -> {\n                int numEntries = buf.getInt();\n                Map<Long, org.apache.pulsar.client.api.MessageId> positions = new HashMap<>();\n                for (int i = 0; i < numEntries; i++) {\n                    long segmentId = buf.getLong();\n                    int msgIdLen = buf.getInt();\n                    byte[] msgIdBytes = new byte[msgIdLen];\n                    buf.get(msgIdBytes);\n                    positions.put(segmentId,\n                            org.apache.pulsar.client.api.MessageId.fromByteArray(msgIdBytes));\n                }\n                yield new CheckpointV5(positions);\n            }\n            default -> throw new IOException(\"Unknown checkpoint type: \" + type);\n        };\n    }\n\n    /**\n     * Sentinel checkpoint for earliest/latest positions. Encoded as a single type byte.\n     */\n    private record SentinelCheckpoint(byte type) implements Checkpoint {\n        @Override\n        public byte[] toByteArray() {\n            ByteBuffer buf = ByteBuffer.allocate(1);\n            buf.put(type);\n            return buf.array();\n        }\n    }\n}\n","sourceCodeStart":83,"sourceCodeEnd":117,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/CheckpointV5.java#L83-L117","documentation":"CheckpointV5.fromByteArray switches on the first byte of the encoding (the checkpoint type). If the type byte does not match any known checkpoint type, it throws IOException('Unknown checkpoint type: N'). This indicates the bytes were not produced by a compatible version of this class.","triggerScenarios":"Deserializing a checkpoint written by a newer client version with additional checkpoint types, or a checkpoint blob that is actually some other payload (wrong topic, wrong record, random bytes).","commonSituations":"Upgrading/downgrading between client versions sharing checkpoint storage; pointing deserialization at a topic or storage key holding non-checkpoint data; endianness or framing mismatch in custom persistence.","solutions":["Ensure the client version reading the checkpoint is >= the version that wrote it.","Verify the byte source actually contains CheckpointV5-encoded data (log the first type byte).","Discard the stale checkpoint and rebuild consumer position from a fresh checkpoint.","If you extended checkpoint types in a fork, update the switch in fromByteArray to handle the new type."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"if (data != null && data.length > 0) {\n    byte type = data[0];\n    if (!KNOWN_CHECKPOINT_TYPES.contains(type)) {\n        log.warn(\"Checkpoint type {} not supported by this client, resetting\", type);\n        return null;\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    checkpoint = CheckpointV5.fromByteArray(data);\n} catch (IOException e) {\n    log.warn(\"Unknown checkpoint type, rebuilding from scratch\", e);\n    checkpoint = CheckpointV5.earliest();\n}","preventionTips":["Pin reader/writer client versions for shared checkpoint storage.","Store a format/version header alongside checkpoints.","On upgrade, migrate or regenerate checkpoints instead of reading them with old code."],"tags":["deserialization","checkpoint","version-compatibility"],"backgroundTag":"unknown-checkpoint-type","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}