{"record":{"id":"fbc96cd1cdee4a6b","repo":"alibaba/canal","slug":"unknown-binlog-version","errorCode":null,"errorMessage":"Unknown binlog version: ","messagePattern":"Unknown binlog version: ","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"dbsync/src/main/java/com/taobao/tddl/dbsync/binlog/event/FormatDescriptionLogEvent.java","lineNumber":146,"sourceCode":"    public static final FormatDescriptionLogEvent FORMAT_DESCRIPTION_EVENT_5_x   = new FormatDescriptionLogEvent(4);\n\n    /** MySQL 4.0.x (x>=2) format descriptions. */\n    public static final FormatDescriptionLogEvent FORMAT_DESCRIPTION_EVENT_4_0_x = new FormatDescriptionLogEvent(3);\n\n    /** MySQL 3.23 format descriptions. */\n    public static final FormatDescriptionLogEvent FORMAT_DESCRIPTION_EVENT_3_23  = new FormatDescriptionLogEvent(1);\n\n    public static FormatDescriptionLogEvent getFormatDescription(final int binlogVersion) throws IOException {\n        /* identify binlog format */\n        switch (binlogVersion) {\n            case 4: /* MySQL 5.0 */\n                return FORMAT_DESCRIPTION_EVENT_5_x;\n            case 3:\n                return FORMAT_DESCRIPTION_EVENT_4_0_x;\n            case 1:\n                return FORMAT_DESCRIPTION_EVENT_3_23;\n            default:\n                throw new IOException(\"Unknown binlog version: \" + binlogVersion);\n        }\n    }\n\n    public FormatDescriptionLogEvent(final int binlogVersion, int binlogChecksum){\n        this(binlogVersion);\n        this.header.checksumAlg = binlogChecksum;\n    }\n\n    public FormatDescriptionLogEvent(final int binlogVersion){\n        this.binlogVersion = binlogVersion;\n\n        postHeaderLen = new short[ENUM_END_EVENT];\n        /* identify binlog format */\n        switch (binlogVersion) {\n            case 4: /* MySQL 5.0 */\n                serverVersion = SERVER_VERSION;\n                commonHeaderLen = LOG_EVENT_HEADER_LEN;\n                numberOfEventTypes = LOG_EVENT_TYPES;","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/dbsync/src/main/java/com/taobao/tddl/dbsync/binlog/event/FormatDescriptionLogEvent.java#L128-L164","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Log the actual binlogVersion value to understand what was read.","Check that the binlog stream position is correct — the version should come from the event header, not from arbitrary data.","Verify the MySQL server version is supported by this parser version.","Upgrade canal/dbsync if a newer MySQL introduced a new binlog format version."],"exampleFix":"// before\nFormatDescriptionLogEvent fd = FormatDescriptionLogEvent.getFormatDescription(binlogVersion);\n\n// after: validate version before calling\nif (binlogVersion != 1 && binlogVersion != 3 && binlogVersion != 4) {\n    logger.warn(\"Unsupported binlog version {}, defaulting to v4\", binlogVersion);\n    binlogVersion = 4;\n}\nFormatDescriptionLogEvent fd = FormatDescriptionLogEvent.getFormatDescription(binlogVersion);","handlingStrategy":"validation","validationCode":"// Validate binlog version before calling getFormatDescription\nif (binlogVersion != 1 && binlogVersion != 3 && binlogVersion != 4) {\n    logger.warn(\"Unknown binlog version {}, falling back to v4\", binlogVersion);\n    binlogVersion = 4; // or handle as error\n}\nFormatDescriptionLogEvent fd = FormatDescriptionLogEvent.getFormatDescription(binlogVersion);","typeGuard":null,"tryCatchPattern":"try {\n    FormatDescriptionLogEvent fd = FormatDescriptionLogEvent.getFormatDescription(binlogVersion);\n} catch (IOException e) {\n    if (e.getMessage().startsWith(\"Unknown binlog version\")) {\n        logger.error(\"Unsupported binlog version: {}, parser may need upgrade\", binlogVersion);\n    }\n    throw e;\n}","preventionTips":["Read and log the binlog version from the event header before calling getFormatDescription.","Keep canal/dbsync updated when upgrading MySQL major versions.","Verify the parser is positioned at the correct offset when reading the version field."],"tags":["binlog","mysql","version-check","format-description","version-compat"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}