{"record":{"id":"540a363beca6372c","repo":"apache/pulsar","slug":"unknown-version-bytesschemaversion-of-schemavers","errorCode":null,"errorMessage":"Unknown version ${BytesSchemaVersion.of(schemaVersion)}","messagePattern":"Unknown version (.+?)","errorType":"exception","errorClass":"SchemaSerializationException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/schema/AbstractStructSchema.java","lineNumber":124,"sourceCode":"    @Override\n    public void setSchemaInfoProvider(SchemaInfoProvider schemaInfoProvider) {\n        if (reader != null) {\n            this.reader.setSchemaInfoProvider(schemaInfoProvider);\n        }\n        this.schemaInfoProvider = schemaInfoProvider;\n    }\n\n    @Override\n    public Schema<T> atSchemaVersion(byte[] schemaVersion) throws SchemaSerializationException {\n        Objects.requireNonNull(schemaVersion);\n        if (schemaInfoProvider == null) {\n            // this schema is not downloaded from the registry\n            return this;\n        }\n        try {\n            SchemaInfo schemaInfo = schemaInfoProvider.getSchemaByVersion(schemaVersion).get();\n            if (schemaInfo == null) {\n                throw new SchemaSerializationException(\"Unknown version \" + BytesSchemaVersion.of(schemaVersion));\n            }\n            return getAbstractStructSchemaAtVersion(schemaVersion, schemaInfo);\n        } catch (ExecutionException err) {\n            throw new SchemaSerializationException(err.getCause());\n        } catch (InterruptedException err) {\n            Thread.currentThread().interrupt();\n            throw new SchemaSerializationException(err);\n        }\n    }\n\n    private static class WrappedVersionedSchema<T> extends AbstractStructSchema<T> {\n        private final byte[] schemaVersion;\n        private final AbstractStructSchema<T> parent;\n        public WrappedVersionedSchema(SchemaInfo schemaInfo, final byte[] schemaVersion,\n                                      AbstractStructSchema<T> parent) {\n            super(schemaInfo);\n            this.schemaVersion = schemaVersion;\n            this.writer = null;","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/schema/AbstractStructSchema.java#L106-L142","documentation":"AbstractStructSchema.atSchemaVersion(byte[]) resolves the SchemaInfo for a given binary schema version from the schema registry provider and builds the schema for that version. If the provider returns null (the version is not known to the registry) it throws this SchemaSerializationException.","triggerScenarios":"Consuming a message whose schemaVersion bytes don't match any schema stored in the broker's schema registry for the topic — e.g. the schema was deleted, the topic's schema was changed and old data versions were removed, or a message crossed topics/clusters with mismatched schemas. Internally fires when getSchemaByVersion(...).get() returns null.","commonSituations":"Topic schema deleted then messages with old versions replayed; cluster replication where the target cluster lacks the schema version; upgrading brokers with schema data loss; consuming from a compacted/bookkept topic after schema evolution cleanup.","solutions":["Re-upload/restore the missing schema version to the topic's schema registry (POST /admin/v2/:tenant/:namespace/:topic/schema).","Resend or skip messages carrying the unknown schema version bytes.","Check replication: ensure the schema exists on all clusters the consumer reads from.","Enable schema auto-update on the producer/consumer and let the client adopt the current schema version."],"exampleFix":"// before\n// consuming old messages after the schema was deleted -> Unknown version error at runtime\n// after\n// restore the schema first:\n// curl -X POST http://broker:8080/admin/v2/public/default/my-topic/schema \\\n//   -H 'Content-Type: application/json' -d '{\"type\":\"AVRO\",\"schema\":\"<base64>\",\"properties\":{}}'","handlingStrategy":"try-catch","validationCode":"// Check the topic's schema versions before consuming old data\n// curl http://broker:8080/admin/v2/<tenant>/<ns>/<topic>/schemas -> compare with message schemaVersion bytes","typeGuard":null,"tryCatchPattern":"try { Schema<?> v = schema.atSchemaVersion(schemaVersionBytes); } catch (SchemaSerializationException e) { log.warn(\"Unknown schema version {} - re-register schema or skip message\", Base64.getEncoder().encodeToString(schemaVersionBytes)); }","preventionTips":["Never delete a topic schema while old data is still readable; re-register schemas before replaying data.","Enable schema auto-update on producers so all clusters register versions consistently.","Verify schema replication across geo-clusters before consuming.","Monitor for messages with schema versions absent from the registry (dead-letter them instead of crashing consumers)."],"tags":["schema","schema-registry","versioning","serialization"],"backgroundTag":"unknown-schema-version","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"}