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.

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 :
• command : 'show binlog events limit 1' has an error! pls…
• command : 'show binlog events limit 1' has an error!
• command : ' + showSql + ' has an error!

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

Appendix: 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)