alibaba/canal · error · CanalClientException

something goes wrong with reason: ${ack.getErrorMessage()}

Error message

something goes wrong with reason: ${ack.getErrorMessage()}

What it means

Thrown by CanalMessageSerializerUtil.deserializer when the parsed CanalPacket.Packet has type ACK rather than MESSAGES. An ACK packet carries a server-side error/ack reason; deserializer converts it into a CanalClientException whose message is 'something goes wrong with reason: <ack.getErrorMessage()>'. This signals the canal server (or a peer) reported an error/exception for the batch rather than returning data. (This exception is then re-wrapped by the outer catch into 'deserializer failed by ...'.)

Source

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

                        }

                        CanalPacket.Messages messages = CanalPacket.Messages.parseFrom(p.getBody());
                        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. Inspect the ack.getErrorMessage() text (surfaced in the exception message) to obtain the server-side reason and address that root cause.
2. Switch on PacketType before calling the MESSAGES deserializer; handle ACK packets via the dedicated ack path rather than deserializer().
3. Verify subscription/filter/permissions on the canal server if the ACK reason indicates an auth or filter error.

Example fix

// before
Message m = CanalMessageSerializerUtil.deserializer(bytes, lazy);  // bytes are an ACK
// after
CanalPacket.Packet p = CanalPacket.Packet.parseFrom(bytes);
if (p.getType() == PacketType.ACK) {
    throw new CanalClientException("server ack: "
        + CanalPacket.Ack.parseFrom(p.getBody()).getErrorMessage());
}
Message m = CanalMessageSerializerUtil.deserializer(bytes, lazy);

// Switch on packet type and route ACKs away from the data deserializer
CanalPacket.Packet p = CanalPacket.Packet.parseFrom(data);
switch (p.getType()) {
    case MESSAGES:
        // safe to deserialize as Message
        break;
    case ACK:
        CanalPacket.Ack ack = CanalPacket.Ack.parseFrom(p.getBody());
        throw new CanalClientException("server ack error: " + ack.getErrorMessage());
    default:
        throw new CanalClientException("unexpected packet type: " + p.getType());
}

boolean isMessagesPacket(byte[] data) throws com.google.protobuf.InvalidProtocolBufferException {
    return CanalPacket.Packet.parseFrom(data).getType()
        == CanalPacket.PacketType.MESSAGES;
}

try {
    Message m = CanalMessageSerializerUtil.deserializer(data, lazyParse);
} catch (CanalClientException e) {
    if (e.getMessage().contains("something goes wrong with reason")) {
        String serverReason = e.getMessage();
        // address the server-side cause; do not treat as a parse bug
        log.error("canal server ACK error: {}", serverReason);
    } else throw e;
}

When it happens

Trigger: A client receives an ACK packet — e.g. a batchId ack/error from the canal server, a subscription/permission error, or an empty/error response — and feeds those bytes into deserializer expecting a data MESSAGES packet.

Common situations: Routing server-control/error ACK bytes through the data deserializer instead of the ack-handling path; server-side filter/permission failure causing an error ACK; protocol misuse where the caller does not switch on packet type before deserializing.

Related errors

• compression is not supported in this connector
• unexpected packet type: ${p.getType()}
• unsupported version at this client.
• expect handshake but found other type.
• unexpected packet type when ack is expected

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