alibaba/canal · error · CanalClientException

unsupported version at this client.

Error message

unsupported version at this client.

What it means

Thrown by SimpleAdminConnector.doConnect() after reading the first protobuf Packet from the canal-server socket: the packet's version field does not equal 1, so the client and server speak incompatible protocol versions.

Source

Thrown at admin/admin-web/src/main/java/com/alibaba/otter/canal/admin/connector/SimpleAdminConnector.java:73

        this.user = user;
        this.passwd = passwd;
    }

    @Override
    public void connect() throws ServiceException {
        try {
            if (connected) {
                return;
            }

            channel = SocketChannel.open();
            channel.socket().setSoTimeout(soTimeout);
            channel.connect(address);
            readableChannel = Channels.newChannel(channel.socket().getInputStream());
            writableChannel = Channels.newChannel(channel.socket().getOutputStream());
            Packet p = Packet.parseFrom(readNextPacket());
            if (p.getVersion() != 1) {
                throw new CanalClientException("unsupported version at this client.");
            }

            if (p.getType() != PacketType.HANDSHAKE) {
                throw new CanalClientException("expect handshake but found other type.");
            }

            Handshake handshake = Handshake.parseFrom(p.getBody());
            ByteString seed = handshake.getSeeds(); // seed for auth
            String newPasswd = passwd;
            if (passwd != null) {
                // encode passwd
                newPasswd = SecurityUtil.byte2HexStr(SecurityUtil.scramble411(passwd.getBytes(), seed.toByteArray()));
            }

            ClientAuth ca = ClientAuth.newBuilder()
                .setUsername(user != null ? user : "")
                .setPassword(ByteString.copyFromUtf8(newPasswd != null ? newPasswd : ""))
                .setNetReadTimeout(idleTimeout)

View on GitHub (pinned to 87be50e876)

Solutions

1. Align canal-admin and canal-server to the same release version (check pom.xml / release tags).
2. Confirm the configured address points to the server's admin port (canal.admin.tcp.port / admin port), not the data port or another service.
3. If interoperating across versions, downgrade/upgrade one side so both use protocol version 1.
4. Inspect the raw handshake bytes to rule out a port misconfiguration returning non-canal data.

Example fix

// before: admin connector pointed at wrong/old server
adminConnector.connect(new InetSocketAddress(serverIp, 11111)); // data port

// after: use the admin port and matching version
adminConnector.connect(new InetSocketAddress(serverIp, 11110)); // admin port

// Validate target before connecting
if (serverVersionKnownIncompatible(adminBuildVersion, serverBuildVersion)) {
    throw new IllegalStateException("Align canal-admin and canal-server versions before connecting");
}

try {
    connector.connect();
} catch (CanalClientException e) {
    if (e.getMessage().contains("unsupported version")) {
        // surface version-mismatch guidance to operator
    }
    throw e;
}

When it happens

Trigger: Admin connector opens a TCP channel to a canal-server admin port, parses the opening Packet, and finds p.getVersion() != 1. Happens when an older/newer server build talks to an incompatible admin-web build.

Common situations: Upgrading canal-admin and canal-server to mismatched versions; pointing the admin connector at a non-canal port (e.g. a ZooKeeper or MySQL port) that returns arbitrary bytes parsed as version != 1; running a fork with a bumped protocol version.

Related errors

• expect handshake but found other type.
• unexpected packet type when ack is expected
• something goes wrong when doing authentication: {}
• end of stream when reading header
• compression is not supported in this connector

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