alibaba/canal · error · CanalClientException

unexpected packet type: ${p.getType()}

Error message

unexpected packet type: ${p.getType()}

What it means

Thrown by CanalMessageSerializerUtil.deserializer when a parsed CanalPacket.Packet has a type other than MESSAGES or ACK. The canal wire protocol defines many packet types (HANDSHAKE, CLIENTAUTH, SUBSCRIPTION, GET, etc.), but this MQ-side deserializer only understands data-carrying MESSAGES packets, so any other type is treated as corrupt or misrouted input. The actual type value is interpolated into the message so you can see which unexpected type arrived.

Source

Thrown at connector/core/src/main/java/com/alibaba/otter/canal/connector/core/util/CanalMessageSerializerUtil.java:123

                        Message result = new Message(messages.getBatchId());
                        if (lazyParseEntry) {
                            // byteString
                            result.setRawEntries(messages.getMessagesList());
                            result.setRaw(true);
                        } else {
                            for (ByteString byteString : messages.getMessagesList()) {
                                result.addEntry(CanalEntry.Entry.parseFrom(byteString));
                            }
                            result.setRaw(false);
                        }
                        return result;
                    }
                    case ACK: {
                        CanalPacket.Ack ack = CanalPacket.Ack.parseFrom(p.getBody());
                        throw new CanalClientException("something goes wrong with reason: " + ack.getErrorMessage());
                    }
                    default: {
                        throw new CanalClientException("unexpected packet type: " + p.getType());
                    }
                }
            }
        } catch (Exception e) {
            throw new CanalClientException("deserializer failed by " + e.getMessage(), e);
        }
    }
}

View on GitHub (pinned to 87be50e876)

Solutions

1. Confirm the bytes came from CanalMessageSerializerUtil.serializer (a CanalPacket.Packet with type MESSAGES) and that you are consuming the correct canal MQ topic.
2. Check canal server and connector versions match — an unknown packet type usually means the client deserializer is older than the producer.
3. If you hold a raw CanalEntry.Entry or RowChange, parse it directly with CanalEntry.Entry.parseFrom / CanalEntry.RowChange.parseFrom instead of routing it through CanalMessageSerializerUtil.deserializer.
4. Inspect p.getType() from the error text to identify which protocol stage produced the packet, then fix the upstream so only MESSAGES packets reach this deserializer.

Example fix

// before
Message msg = CanalMessageSerializerUtil.deserializer(data);

// after — guard against non-MESSAGES bytes before deserializing
CanalPacket.Packet p = CanalPacket.Packet.parseFrom(data);
if (p.getType() != CanalPacket.PacketType.MESSAGES) {
    throw new IllegalArgumentException("expect MESSAGES packet, got " + p.getType());
}
Message msg = CanalMessageSerializerUtil.deserializer(data);

// Validate the payload is a MESSAGES packet before deserializing
CanalPacket.Packet p = CanalPacket.Packet.parseFrom(data);
if (p.getType() != CanalPacket.PacketType.MESSAGES) {
    throw new IllegalArgumentException(
        "Cannot deserialize non-MESSAGES packet: " + p.getType());
}
Message msg = CanalMessageSerializerUtil.deserializer(data);

static boolean isCanalMessagesPacket(byte[] data) {
    try {
        return CanalPacket.Packet.parseFrom(data).getType()
            == CanalPacket.PacketType.MESSAGES;
    } catch (com.google.protobuf.InvalidProtocolBufferException e) {
        return false;
    }
}

try {
    Message msg = CanalMessageSerializerUtil.deserializer(data);
} catch (CanalClientException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("unexpected packet type")) {
        // wrong source / version mismatch — do not retry, fix upstream
        log.error("Non-MESSAGES packet received; check topic and canal versions", e);
    }
    throw e;
}

When it happens

Trigger: CanalMessageSerializerUtil.deserializer(data) is called on a byte[] that was not produced by CanalMessageSerializerUtil.serializer — for example bytes from a canal server handshake/auth response, a raw protobuf that is not a CanalPacket.Packet, or bytes read off the wrong MQ topic. Also reachable when a producer sends a custom packet type the consumer switch does not case on.

Common situations: Subscribing a canal MQ consumer to a topic that carries non-canal payloads; version skew where a newer canal server emits a packet type the older connector deserializer does not know; feeding the deserializer a raw Entry/RowChange byte array instead of a full Packet; reading a handshake-stage message that leaked into the data path.

Related errors

• deserializer failed by ${e.getMessage()}
• ERROR ## parser of eromanga-event has an error , data:${entr
• unsupported version at this client.
• Error when serializing message to byte[] by ${e.getMessage()
• compression is not supported in this connector

AI-assisted analysis of alibaba/canal@87be50e876 (2026-08-14). Data as JSON: /api/errors/371ad433690786f5. Report an issue: GitHub.