alibaba/canal · error · IOException

Error When doing Register slave: + err.toString()

Error message

Error When doing Register slave: + err.toString()

What it means

During sendRegisterSlave(), after sending the COM_REGISTER_SLAVE packet the server replied with an error packet (first byte == -1, i.e. 0xff). Canal decodes it as an ErrorPacket and throws an IOException carrying the server's error text. This is a server-side rejection of the slave-registration handshake that precedes a binlog dump.

Source

Thrown at parse/src/main/java/com/alibaba/otter/canal/parse/inbound/mysql/MysqlConnection.java:339

        cmd.reportUser = authInfo.getUsername();
        cmd.serverId = this.slaveId;
        byte[] cmdBody = cmd.toBytes();

        logger.info("Register slave {}", cmd);

        HeaderPacket header = new HeaderPacket();
        header.setPacketBodyLength(cmdBody.length);
        header.setPacketSequenceNumber((byte) 0x00);
        PacketManager.writePkg(connector.getChannel(), header.toBytes(), cmdBody);

        header = PacketManager.readHeader(connector.getChannel(), 4);
        byte[] body = PacketManager.readBytes(connector.getChannel(), header.getPacketBodyLength());
        assert body != null;
        if (body[0] < 0) {
            if (body[0] == -1) {
                ErrorPacket err = new ErrorPacket();
                err.fromBytes(body);
                throw new IOException("Error When doing Register slave:" + err.toString());
            } else {
                throw new IOException("Unexpected packet with field_count=" + body[0]);
            }
        }
    }

    private void sendBinlogDump(String binlogfilename, Long binlogPosition) throws IOException {
        BinlogDumpCommandPacket binlogDumpCmd = new BinlogDumpCommandPacket();
        binlogDumpCmd.binlogFileName = binlogfilename;
        binlogDumpCmd.binlogPosition = binlogPosition;
        binlogDumpCmd.slaveServerId = this.slaveId;
        byte[] cmdBody = binlogDumpCmd.toBytes();

        logger.info("COM_BINLOG_DUMP with position:{}", binlogDumpCmd);
        HeaderPacket binlogDumpHeader = new HeaderPacket();
        binlogDumpHeader.setPacketBodyLength(cmdBody.length);
        binlogDumpHeader.setPacketSequenceNumber((byte) 0x00);
        PacketManager.writePkg(connector.getChannel(), binlogDumpHeader.toBytes(), cmdBody);

View on GitHub (pinned to 87be50e876)

Solutions

1. Grant the replication account: GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'canal'@'%'.
2. Ensure canal.instance.slaveId is unique across all replicas connected to the same master (collision yields a server-side error).
3. Check the embedded err.toString() in the exception for the exact MySQL error code/message and address that specifically (e.g. ER_MASTER_FATAL_ERROR_READING_BINLOG, host rejection).
4. If the master enforces skip-name-resolve, ensure canal's reported host matches an allowed host entry.

// Around the dump/start that triggers sendRegisterSlave()
try {
    connection.dump(journalName, position, coprocessor);
} catch (IOException e) {
    if (e.getMessage() != null && e.getMessage().contains("Register slave")) {
        logger.error("Slave registration rejected by master; check REPLICATION SLAVE privilege and server_id uniqueness", e);
        // surface a clear ops error, do not silently retry in a tight loop
    }
    throw e;
}

When it happens

Trigger: The MySQL/MariaDB server returns error 0xff to COM_REGISTER_SLAVE. Typical causes: the connecting user lacks REPLICATION SLAVE privilege, the reported slave host/port is rejected, server_id collision, max replication connections reached, or skip-name-resolve / firewall rejecting the reported host.

Common situations: Account used by canal does not have GRANT REPLICATION SLAVE, REPLICATION CLIENT; another canal/replica already registered the same server_id; the reported reportHost resolves to something the master refuses (DNS / bind-address).

Related errors

• Unexpected packet with field_count= + body[0]
• Received error packet: errno = {}, sqlstate = {} errmsg = {}
• unexpected binlog format query result: + rs.getFieldValues()
• command : show variables like 'server_id' has an error! pls
• command : show variables like 'server_id' has an error!

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