apache/pulsar · error · SchemaSerializationException

Size of data received by ByteSchema is not 1

Error message

Size of data received by ByteSchema is not 1

What it means

ByteSchema stores a signed 8-bit value in exactly one byte. Its byte[]-based validate() throws SchemaSerializationException when the array length is not 1, preventing misaligned or corrupted payloads from being silently misdecoded.

Solutions

1. Publish with Schema.INT8 on the producer side so payloads are 1 byte
2. Confirm the topic schema actually matches INT8 (inspect with pulsar-admin schemas get)
3. Validate payload.length == 1 before decoding manually

Example fix

// before
byte v = byteSchema.decode(payload); // throws if length != 1
// after
if (payload.length == 1) {
    byte v = byteSchema.decode(payload);
} else {
    throw new IllegalArgumentException("Unexpected payload size: " + payload.length);
}

if (message == null || message.length != 1) {
    throw new IllegalArgumentException("INT8 payload must be exactly 1 byte");
}

boolean isValidBytePayload(byte[] msg) {
    return msg != null && msg.length == 1;
}

try {
    schema.validate(message);
} catch (SchemaSerializationException e) {
    log.warn("Malformed INT8 payload, length={}", message == null ? -1 : message.length);
}

When it happens

Trigger: Calling Schema.INT8/ByteSchema.validate(byte[]) with an empty or multi-byte array — e.g. decoding a message produced with a different schema (INT32, string, Avro) into an INT8 topic.

Common situations: Schema mismatch between producer and consumer; manual deserialization of raw topic bytes; migration from another system emitting differently sized integers.

Related errors

• Size of data received by BooleanSchema is not 1
• Size of data received by DoubleSchema is not 8
• Can not enable for all producers but denies for…
• Can't get accurate schema information for topic
• This method is not supported

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

Appendix: source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/schema/ByteSchema.java:49

    private static final ByteSchema INSTANCE;
    private static final SchemaInfo SCHEMA_INFO;

    static {
        SCHEMA_INFO = SchemaInfoImpl.builder()
            .name("INT8")
            .type(SchemaType.INT8)
            .schema(new byte[0]).build();
        INSTANCE = new ByteSchema();
    }

    public static ByteSchema of() {
        return INSTANCE;
    }

    @Override
    public void validate(byte[] message) {
        if (message.length != 1) {
            throw new SchemaSerializationException("Size of data received by ByteSchema is not 1");
        }
    }

    @Override
    public void validate(ByteBuf message) {
        if (message.readableBytes() != 1) {
            throw new SchemaSerializationException("Size of data received by ByteSchema is not 1");
        }
    }

    @Override
    public byte[] encode(Byte message) {
        if (null == message) {
            return null;
        } else {
            return new byte[]{message};
        }
    }

View on GitHub (pinned to 820761864e)