alibaba/canal · error · CanalClientException
failed to subscribe with reason:
Error message
failed to subscribe with reason:
What it means
Error "failed to subscribe with reason: " thrown in alibaba/canal.
Source
Thrown at client/src/main/java/com/alibaba/otter/canal/client/impl/SimpleCanalConnector.java:253
if (!running) {
return;
}
try {
writeWithHeader(Packet.newBuilder()
.setType(PacketType.SUBSCRIPTION)
.setBody(Sub.newBuilder()
.setDestination(clientIdentity.getDestination())
.setClientId(String.valueOf(clientIdentity.getClientId()))
.setFilter(filter != null ? filter : "")
.build()
.toByteString())
.build()
.toByteArray());
//
Packet p = Packet.parseFrom(readNextPacket());
Ack ack = Ack.parseFrom(p.getBody());
if (ack.getErrorCode() > 0) {
throw new CanalClientException("failed to subscribe with reason: " + ack.getErrorMessage());
}
clientIdentity.setFilter(filter);
} catch (IOException e) {
throw new CanalClientException(e);
}
}
@Override
public void unsubscribe() throws CanalClientException {
waitClientRunning();
if (!running) {
return;
}
try {
writeWithHeader(Packet.newBuilder()
.setType(PacketType.UNSUBSCRIPTION)
.setBody(Unsub.newBuilder()View on GitHub (pinned to 87be50e876)
Solutions
- Read the reason string returned by the server; common causes are an invalid destination name or an invalid filter expression.
- Verify the destination exists and is started: check server logs or the admin console.
- Validate the subscribe filter syntax (e.g. db\\..* or db.table) against the canal filter rules.
When it happens
Trigger: Thrown at client/src/main/java/com/alibaba/otter/canal/client/impl/SimpleCanalConnector.java:253 when the library encounters an invalid state.
Common situations: Subscribe rejected by server. Validate destination, filter expression, and client identity before resubscribing; log the server-provided reason verbatim.
AI-assisted analysis of alibaba/canal@87be50e876 (2026-08-14).
Data as JSON: /api/errors/8a441467d9437e4e.
Report an issue: GitHub.