alibaba/canal · error · IOException

Format Description event header length is too short

Error message

Format Description event header length is too short

What it means

Thrown during construction of a FormatDescriptionLogEvent when the common header length field read from the event is less than OLD_HEADER_LEN (the minimum valid common header size for the binlog format). This sanity check ensures the event declares a header large enough to contain the required fields. A too-short header means the binlog format is either corrupt or from an unrecognized source.

Source

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

     * LOG_EVENT_MINIMAL_HEADER_LEN).
     */
    protected final int       commonHeaderLen;
    protected int             numberOfEventTypes;

    /** The list of post-headers' lengthes */
    protected final short[]   postHeaderLen;
    protected int[]           serverVersionSplit                  = new int[3];

    public FormatDescriptionLogEvent(LogHeader header, LogBuffer buffer, FormatDescriptionLogEvent descriptionEvent)
                                                                                                                    throws IOException{
        /* Start_log_event_v3 */
        super(header, buffer, descriptionEvent);

        buffer.position(LOG_EVENT_MINIMAL_HEADER_LEN + ST_COMMON_HEADER_LEN_OFFSET);
        commonHeaderLen = buffer.getUint8();
        if (commonHeaderLen < OLD_HEADER_LEN) /* sanity check */
        {
            throw new IOException("Format Description event header length is too short");
        }

        numberOfEventTypes = buffer.limit() - (LOG_EVENT_MINIMAL_HEADER_LEN + ST_COMMON_HEADER_LEN_OFFSET + 1);

        // buffer.position(LOG_EVENT_MINIMAL_HEADER_LEN
        // + ST_COMMON_HEADER_LEN_OFFSET + 1);
        postHeaderLen = new short[numberOfEventTypes];
        for (int i = 0; i < numberOfEventTypes; i++) {
            postHeaderLen[i] = (short) buffer.getUint8();
        }

        calcServerVersionSplit();
        long calc = getVersionProduct();
        if (calc >= checksumVersionProduct) {
            /*
             * the last bytes are the checksum alg desc and value (or value's room)
             */
            numberOfEventTypes -= BINLOG_CHECKSUM_ALG_DESC_LEN;

View on GitHub (pinned to 87be50e876)

Solutions

1. Verify the binlog file is from a supported MySQL version (3.23, 4.0, 4.x, 5.x, 8.x).
2. Check that the parser is positioned at the actual start of a FORMAT_DESCRIPTION_EVENT — if the position is wrong, the header bytes will be misinterpreted.
3. Use mysqlbinlog to verify the file is valid and readable.
4. Check for binlog file corruption (incomplete writes, disk errors).

// Pre-validate before constructing FormatDescriptionLogEvent
buffer.position(LOG_EVENT_MINIMAL_HEADER_LEN + ST_COMMON_HEADER_LEN_OFFSET);
int headerLen = buffer.getUint8();
if (headerLen < FormatDescriptionLogEvent.OLD_HEADER_LEN) {
    logger.warn("Format description common header len {} is below minimum {}",
        headerLen, FormatDescriptionLogEvent.OLD_HEADER_LEN);
    // use default format description
}

try {
    FormatDescriptionLogEvent fd = new FormatDescriptionLogEvent(header, buffer, descriptionEvent);
} catch (IOException e) {
    if (e.getMessage().contains("header length is too short")) {
        logger.error("Binlog format description header too short — corrupt or unsupported format");
    }
    throw e;
}

When it happens

Trigger: Constructing FormatDescriptionLogEvent from a binlog stream. At offset LOG_EVENT_MINIMAL_HEADER_LEN + ST_COMMON_HEADER_LEN_OFFSET, a uint8 is read as commonHeaderLen. If commonHeaderLen < OLD_HEADER_LEN, the exception fires.

Common situations: Binlog from an unsupported MySQL/MariaDB version with a different format description structure, a corrupt or truncated binlog file, or the parser is positioned at the wrong offset (not actually at a FORMAT_DESCRIPTION_EVENT).

Related errors

• Unknown binlog version:
• unknow compress type for :
• Query event length is too short.
• No such method: '{}' @ {}
• No such field: '{}' @ {}

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