apache/pulsar · error · SchemaSerializationException

This method cannot be used under this SEPARATED encoding typ

Error message

This method cannot be used under this SEPARATED encoding type

What it means

KeyValueSchemaImpl.decode(byte[], byte[]) decodes an INLINE-encoded KeyValue (key and value concatenated in one buffer). If the schema was configured with KeyValueEncodingType.SEPARATED, key and value are stored separately and this method cannot decode them, so it throws SchemaSerializationException.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/schema/KeyValueSchemaImpl.java:184

                message.getValue(),
                valueSchema);
        } else {
            if (message.getValue() == null) {
                return null;
            }
            return valueSchema.encode(topic, message.getValue());
        }
    }

    @Override
    public KeyValue<K, V> decode(byte[] bytes) {
        return decode(bytes, null);
    }

    @Override
    public KeyValue<K, V> decode(byte[] bytes, byte[] schemaVersion) {
        if (this.keyValueEncodingType == KeyValueEncodingType.SEPARATED) {
            throw new SchemaSerializationException("This method cannot be used under this SEPARATED encoding type");
        }
        return KeyValue.decode(bytes, (keyBytes, valueBytes) -> decode(keyBytes, valueBytes, schemaVersion));
    }

    @Override
    public KeyValue<K, V> decode(ByteBuf byteBuf) {
        return decode(ByteBufUtil.getBytes(byteBuf));
    }

    @Override
    public KeyValue<K, V> decode(String topic, byte[] data, byte[] schemaId) {
        if (this.keyValueEncodingType == KeyValueEncodingType.SEPARATED) {
            throw new SchemaSerializationException("This method cannot be used under this SEPARATED encoding type");
        }
        return KeyValue.decode(data, (keyBytes, valueBytes) ->
                decode(topic, keyBytes, valueBytes, schemaId));
    }

View on GitHub (pinned to 820761864e)

Solutions

Use decode(ByteBuf) with the separate key/value ByteBufs, or the decode(String topic, byte[] keyBytes, byte[] valueBytes, ...) variant for SEPARATED encoding
Re-create the KeyValue schema with KeyValueEncodingType.INLINE if you want single-buffer decode
Use Message.getValue() on the consumer which handles the configured encoding automatically

Example fix

// before
KeyValue<K,V> kv = kvSchema.decode(payload);
// after
if (message.getReaderSchema() instanceof KeyValueSchemaImpl && ((KeyValueSchemaImpl)message.getReaderSchema()).getKeyValueEncodingType() == KeyValueEncodingType.SEPARATED) { KeyValue<K,V> kv = (KeyValue<K,V>) message.getValue(); } else { KeyValue<K,V> kv = kvSchema.decode(payload); }

Defensive patterns

Strategy: type-guard

Validate before calling

if (kvSchema instanceof KeyValueSchemaImpl && ((KeyValueSchemaImpl<?,?>) kvSchema).getKeyValueEncodingType() == KeyValueEncodingType.SEPARATED) { /* use separate-decode path */ }

Type guard

static <K,V> boolean isSeparated(Schema<KeyValue<K,V>> s) { return s instanceof KeyValueSchemaImpl && ((KeyValueSchemaImpl<?,?>) s).getKeyValueEncodingType() == KeyValueEncodingType.SEPARATED; }

Try / catch

try { KeyValue<K,V> kv = kvSchema.decode(bytes, schemaVersion); } catch (SchemaSerializationException e) { if (e.getMessage().contains("SEPARATED")) { kv = (KeyValue<K,V>) message.getValue(); } else throw e; }

Prevention

Always decode via Message.getValue() instead of raw bytes
Keep the KeyValueEncodingType constant shared between producer and consumer configs
Document the encoding type next to each KeyValue schema instance

When it happens

Trigger: Creating Schema.KeyValue(..., KeyValueEncodingType.SEPARATED) and then calling kvSchema.decode(bytes) or kvSchema.decode(bytes, schemaVersion) on a single combined byte array.

Common situations: Consuming a SEPARATED KeyValue topic with a decode call that assumes inline encoding; switching encoding type in producer code without updating consumer decode calls.

Related errors

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