What causes "This schema is not meant to be used for encoding" in apache/pulsar?

Use the original typed schema (e.g. Schema.AVRO(MyPojo.class)) on the producer instead of the consumer-side struct schema

apache/pulsar · error · UnsupportedOperationException

This schema is not meant to be used for encoding

Error message

This schema is not meant to be used for encoding

What it means

AbstractStructSchema's encode() is deliberately unimplemented: struct schemas (Avro/Protobuf/JSON based, multi-version readers) are designed for decoding only on the consumer side. Calling encode() throws UnsupportedOperationException to signal that this schema instance cannot serialize messages back to bytes.

Source

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

        @Override
        public boolean requireFetchingSchemaInfo() {
            return true;
        }

        @Override
        public T decode(byte[] bytes) {
            return decode(bytes, schemaVersion);
        }

        @Override
        public T decode(ByteBuf byteBuf) {
            return decode(byteBuf, schemaVersion);
        }

        @Override
        public byte[] encode(T message) {
            throw new UnsupportedOperationException("This schema is not meant to be used for encoding");
        }

        @Override
        @SuppressWarnings("unchecked")
        public Optional<Object> getNativeSchema() {
            if (reader instanceof AbstractMultiVersionReader) {
                AbstractMultiVersionReader abstractMultiVersionReader = (AbstractMultiVersionReader) reader;
                try {
                    SchemaReader schemaReader = abstractMultiVersionReader.getSchemaReader(schemaVersion);
                    return schemaReader.getNativeSchema();
                } catch (ExecutionException err) {
                    throw new RuntimeException(err.getCause());
                }
            } else {
                return Optional.empty();
            }
        }

View on GitHub (pinned to 820761864e)

Solutions

Use the original typed schema (e.g. Schema.AVRO(MyPojo.class)) on the producer instead of the consumer-side struct schema
If you need both directions, create a separate schema instance for encoding rather than reusing the decoding schema
If the value is a GenericRecord, use a schema built from its SchemaInfo (e.g. Schema.generic(schemaInfo)) that supports encoding

Example fix

// before
Schema<MyPojo> schema = consumer.getSchema();
byte[] bytes = schema.encode(myPojo); // throws
// after
Schema<MyPojo> schema = Schema.AVRO(MyPojo.class);
byte[] bytes = schema.encode(myPojo);

Defensive patterns

Strategy: validation

Validate before calling

if (schema instanceof AbstractStructSchema || !schemaSupportsEncode(schema)) {
    throw new IllegalStateException("Schema cannot encode; use a producer-side typed schema");
}
boolean schemaSupportsEncode(Schema<?> s) {
    return !(s instanceof AutoConsumeSchema) && !(s.getClass().getSimpleName().contains("MultiVersion"));
}

Type guard

boolean isEncodeCapable(Schema<?> s) {
    return s != null && !(s instanceof AutoConsumeSchema) && !(s instanceof AbstractStructSchema);
}

Try / catch

try {
    byte[] bytes = schema.encode(message);
} catch (UnsupportedOperationException e) {
    // fall back to a producer-side schema
    bytes = Schema.AVRO(Message.class).encode(message);
}

Prevention

Never reuse consumer-side schemas (AutoConsumeSchema, lookup-based struct schemas) for producing
Create dedicated producer schemas with Schema.AVRO/JSON/Protobuf(Class)
Check instanceof before calling encode in generic schema-agnostic code

When it happens

Trigger: Calling schema.encode(message) on an AbstractStructSchema instance (e.g. a schema obtained via AutoConsumeSchema, schema registry lookup, or reader-side multi-version schema) instead of using the original typed schema created for producing.

Common situations: Developers fetch a schema via Schema.AVRO(...) lookup from a broker or via AutoConsumeSchema on the consumer side and then try to reuse it on a producer to publish records; or generic code paths that assume every Schema supports encode().

Related errors

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