alibaba/canal · error · IOException

Unknown binlog version:

Error message

Unknown binlog version: 

What it means

Thrown by FormatDescriptionLogEvent.getFormatDescription() when the binlog version number does not match any known version: 4 (MySQL 5.0+), 3 (MySQL 4.0/4.1), or 1 (MySQL 3.23). The binlog version is read from the binlog file header and determines the event format used throughout the stream.

Source

Thrown at dbsync/src/main/java/com/taobao/tddl/dbsync/binlog/event/FormatDescriptionLogEvent.java:146

    public static final FormatDescriptionLogEvent FORMAT_DESCRIPTION_EVENT_5_x   = new FormatDescriptionLogEvent(4);

    /** MySQL 4.0.x (x>=2) format descriptions. */
    public static final FormatDescriptionLogEvent FORMAT_DESCRIPTION_EVENT_4_0_x = new FormatDescriptionLogEvent(3);

    /** MySQL 3.23 format descriptions. */
    public static final FormatDescriptionLogEvent FORMAT_DESCRIPTION_EVENT_3_23  = new FormatDescriptionLogEvent(1);

    public static FormatDescriptionLogEvent getFormatDescription(final int binlogVersion) throws IOException {
        /* identify binlog format */
        switch (binlogVersion) {
            case 4: /* MySQL 5.0 */
                return FORMAT_DESCRIPTION_EVENT_5_x;
            case 3:
                return FORMAT_DESCRIPTION_EVENT_4_0_x;
            case 1:
                return FORMAT_DESCRIPTION_EVENT_3_23;
            default:
                throw new IOException("Unknown binlog version: " + binlogVersion);
        }
    }

    public FormatDescriptionLogEvent(final int binlogVersion, int binlogChecksum){
        this(binlogVersion);
        this.header.checksumAlg = binlogChecksum;
    }

    public FormatDescriptionLogEvent(final int binlogVersion){
        this.binlogVersion = binlogVersion;

        postHeaderLen = new short[ENUM_END_EVENT];
        /* identify binlog format */
        switch (binlogVersion) {
            case 4: /* MySQL 5.0 */
                serverVersion = SERVER_VERSION;
                commonHeaderLen = LOG_EVENT_HEADER_LEN;
                numberOfEventTypes = LOG_EVENT_TYPES;

View on GitHub (pinned to 87be50e876)

Solutions

1. Log the actual binlogVersion value to understand what was read.
2. Check that the binlog stream position is correct — the version should come from the event header, not from arbitrary data.
3. Verify the MySQL server version is supported by this parser version.
4. Upgrade canal/dbsync if a newer MySQL introduced a new binlog format version.

Example fix

// before
FormatDescriptionLogEvent fd = FormatDescriptionLogEvent.getFormatDescription(binlogVersion);

// after: validate version before calling
if (binlogVersion != 1 && binlogVersion != 3 && binlogVersion != 4) {
    logger.warn("Unsupported binlog version {}, defaulting to v4", binlogVersion);
    binlogVersion = 4;
}
FormatDescriptionLogEvent fd = FormatDescriptionLogEvent.getFormatDescription(binlogVersion);

// Validate binlog version before calling getFormatDescription
if (binlogVersion != 1 && binlogVersion != 3 && binlogVersion != 4) {
    logger.warn("Unknown binlog version {}, falling back to v4", binlogVersion);
    binlogVersion = 4; // or handle as error
}
FormatDescriptionLogEvent fd = FormatDescriptionLogEvent.getFormatDescription(binlogVersion);

try {
    FormatDescriptionLogEvent fd = FormatDescriptionLogEvent.getFormatDescription(binlogVersion);
} catch (IOException e) {
    if (e.getMessage().startsWith("Unknown binlog version")) {
        logger.error("Unsupported binlog version: {}, parser may need upgrade", binlogVersion);
    }
    throw e;
}

When it happens

Trigger: Calling FormatDescriptionLogEvent.getFormatDescription(binlogVersion) with a version value that is not 1, 3, or 4. The version is typically read from the START_EVENT_V3 or FORMAT_DESCRIPTION_EVENT header in the binlog.

Common situations: A new MySQL/MariaDB version introduces binlog format version 5+, the binlog header is corrupt producing a random version number, or the parser is positioned at the wrong offset in the stream and reads a data byte as the version number.

Related errors

• Format Description event header length is too short
• unknow compress type for :
• No such method: '{}' @ {}
• No such field: '{}' @ {}
• Unable to unwrap {} to com.mysql.jdbc.ConnectionImpl

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