apache/pulsar · error · SchemaSerializationException

Unknown version ${BytesSchemaVersion.of(schemaVersion)}

Error message

Unknown version ${BytesSchemaVersion.of(schemaVersion)}

What it means

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.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/schema/AbstractStructSchema.java:124

    @Override
    public void setSchemaInfoProvider(SchemaInfoProvider schemaInfoProvider) {
        if (reader != null) {
            this.reader.setSchemaInfoProvider(schemaInfoProvider);
        }
        this.schemaInfoProvider = schemaInfoProvider;
    }

    @Override
    public Schema<T> atSchemaVersion(byte[] schemaVersion) throws SchemaSerializationException {
        Objects.requireNonNull(schemaVersion);
        if (schemaInfoProvider == null) {
            // this schema is not downloaded from the registry
            return this;
        }
        try {
            SchemaInfo schemaInfo = schemaInfoProvider.getSchemaByVersion(schemaVersion).get();
            if (schemaInfo == null) {
                throw new SchemaSerializationException("Unknown version " + BytesSchemaVersion.of(schemaVersion));
            }
            return getAbstractStructSchemaAtVersion(schemaVersion, schemaInfo);
        } catch (ExecutionException err) {
            throw new SchemaSerializationException(err.getCause());
        } catch (InterruptedException err) {
            Thread.currentThread().interrupt();
            throw new SchemaSerializationException(err);
        }
    }

    private static class WrappedVersionedSchema<T> extends AbstractStructSchema<T> {
        private final byte[] schemaVersion;
        private final AbstractStructSchema<T> parent;
        public WrappedVersionedSchema(SchemaInfo schemaInfo, final byte[] schemaVersion,
                                      AbstractStructSchema<T> parent) {
            super(schemaInfo);
            this.schemaVersion = schemaVersion;
            this.writer = null;

View on GitHub (pinned to 820761864e)

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.

Example fix

// before
// consuming old messages after the schema was deleted -> Unknown version error at runtime
// after
// restore the schema first:
// curl -X POST http://broker:8080/admin/v2/public/default/my-topic/schema \
//   -H 'Content-Type: application/json' -d '{"type":"AVRO","schema":"<base64>","properties":{}}'

Defensive patterns

Strategy: try-catch

Validate before calling

// Check the topic's schema versions before consuming old data
// curl http://broker:8080/admin/v2/<tenant>/<ns>/<topic>/schemas -> compare with message schemaVersion bytes

Try / catch

try { Schema<?> v = schema.atSchemaVersion(schemaVersionBytes); } catch (SchemaSerializationException e) { log.warn("Unknown schema version {} - re-register schema or skip message", Base64.getEncoder().encodeToString(schemaVersionBytes)); }

Prevention

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).

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/540a363beca6372c. Report an issue: GitHub.