alibaba/canal · error · IllegalArgumentException

unknow useconds meta :

Error message

unknow useconds meta : 

What it means

Thrown by usecondsToStr(int frac, int meta) when formatting the fractional (microsecond) part of a TIME/DATE/TIMESTAMP/DATETIME value. meta is the fractional-seconds precision (fsp) from the column metadata; MySQL supports fsp 0-6. A meta > 6 is impossible for a valid MySQL temporal type, so this guard catches corrupt metadata before it produces a nonsense string.

Source

Thrown at dbsync/src/main/java/com/taobao/tddl/dbsync/binlog/event/RowsLogBuffer.java:1158

        return fNull;
    }

    public final int getJavaType() {
        return javaType;
    }

    public final Serializable getValue() {
        return value;
    }

    public final int getLength() {
        return length;
    }

    public static String usecondsToStr(int frac, int meta) {
        String sec = String.valueOf(frac);
        if (meta > 6) {
            throw new IllegalArgumentException("unknow useconds meta : " + meta);
        }

        if (sec.length() < 6) {
            StringBuilder result = new StringBuilder(6);
            int len = 6 - sec.length();
            for (; len > 0; len--) {
                result.append('0');
            }
            result.append(sec);
            sec = result.toString();
        }

        return sec.substring(0, meta);
    }

    public static void appendNumber4(StringBuilder builder, int d) {
        if (d >= 1000) {
            builder.append(digits[d / 1000])

View on GitHub (pinned to 87be50e876)

Solutions

1. Verify the temporal column's fractional precision on the master (must be 0-6).
2. Inspect the Table_map event and the offending row event with mysqlbinlog --hexdump.
3. Upgrade Canal to match the master version in case metadata encoding changed.
4. Filter the table if the temporal column is not required.

Example fix

// before
if (meta > 6) {
    throw new IllegalArgumentException("unknow useconds meta : " + meta);
}
// after: clamp to a valid precision and warn
if (meta > 6) {
    logger.warn("Unexpected useconds meta {}, clamping to 6", meta);
    meta = 6;
}

static final int MAX_FSP = 6; // MySQL max fractional seconds precision
boolean isValidUsecondsMeta(int meta) {
    return meta >= 0 && meta <= MAX_FSP;
}

try {
    RowsLogBuffer.usecondsToStr(frac, meta);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("unknow useconds meta")) {
        // clamp and continue rather than abort the row
        logger.warn("Invalid fsp meta={}, clamping to 6", meta);
        meta = 6;
    } else throw e;
}

When it happens

Trigger: A temporal column whose table-map metadata encodes a fractional precision > 6. Only reachable if the column metadata is corrupt or misread, since MySQL caps fsp at 6.

Common situations: Binlog corruption affecting a TIME(6)/DATETIME(6)/TIMESTAMP(6) column; a MySQL fork emitting non-standard fsp; buffer misalignment causing meta to be read from the wrong offset.

Related errors

• !! Don't know how to handle column type=%d meta=%d (%04X)
• !! Unknown Bit len =
• !! Unknown ENUM packlen =
• !! Unknown Set len =
• !! Unknown BLOB packlen =

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