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.

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)

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 replicators,
• This method is not supported
• Can't get accurate schema information for topic ${topicName}

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