apache/shardingsphere · error · UnsupportedSQLOperationException

MySQL BLOB type meta in binlog should be range 1 to 4, but a

Error message

MySQL BLOB type meta in binlog should be range 1 to 4, but actual value is: %s

What it means

Thrown while decoding a MySQL BLOB column value from a binlog row event: the column metadata (length bytes indicator) must be 1–4 and determines how the blob length prefix is read (1/2/3/4 bytes). Any other value is not understood and throws UnsupportedSQLOperationException. It indicates the binlog event's table metadata does not match any known BLOB encoding.

Source

Thrown at database/protocol/dialect/mysql/src/main/java/org/apache/shardingsphere/database/protocol/mysql/packet/binlog/row/column/value/blob/MySQLBlobBinlogProtocolValue.java:48

public final class MySQLBlobBinlogProtocolValue implements MySQLBinlogProtocolValue {
    
    @Override
    public Serializable read(final MySQLBinlogColumnDef columnDef, final MySQLPacketPayload payload) {
        return payload.readStringFixByBytes(readLengthFromMeta(columnDef.getColumnMeta(), payload));
    }
    
    private int readLengthFromMeta(final int columnMeta, final MySQLPacketPayload payload) {
        switch (columnMeta) {
            case 1:
                return payload.getByteBuf().readUnsignedByte();
            case 2:
                return payload.getByteBuf().readUnsignedShortLE();
            case 3:
                return payload.getByteBuf().readUnsignedMediumLE();
            case 4:
                return payload.readInt4();
            default:
                throw new UnsupportedSQLOperationException(String.format("MySQL BLOB type meta in binlog should be range 1 to 4, but actual value is: %s", columnMeta));
        }
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Confirm the MySQL server version producing the binlog is supported by the proxy's binlog parser
2. Dump the offending binlog event with mysqlbinlog --base64-output=DECODE-ROWS -vv and check the table map metadata for the BLOB column
3. Check whether the table schema changed (ALTER on the blob column) while events were being consumed, desyncing the table map cache
4. Report the column meta value and server version upstream so the case can be classified or supported

// before decoding a blob column from a row event, check the table-map meta
int columnMeta = columnDefinition.getColumnMeta();
if (columnMeta < 1 || columnMeta > 4) {
    // stale/foreign TABLE_MAP: resubscribe or skip the event instead of throwing mid-decode
    resyncFromCurrentPosition();
    return;
}

try {
    value = blobValue.read(columnMeta, payload);
} catch (UnsupportedSQLOperationException ex) {
    // unsupported blob meta width: skip this event, log the binlog position and server version,
    // and resynchronize the table map cache before the next event
    skipEventAndResync(eventHeader, ex);
}

When it happens

Trigger: Calling readLengthFromMeta() with a columnMeta outside 1–4 while parsing a WRITE_ROWS/UPDATE_ROWS event for a BLOB/TEXT column in MySQLBlobBinlogProtocolValue.

Common situations: Binlogs from unsupported MySQL/MariaDB versions or unusual settings; a mispositioned event reader that consumed the wrong metadata offset; AliSQL/other forks adding new blob encodings.

Related errors

• MySQL JSON type meta in binlog should be range 1 to 4, but a
• MySQL Enum meta in binlog only include value 1 or 2, but act
• 6
• Decode binlog event failed, errorCode: %d, sqlState: %s, err
• Can not support type `%s`.

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/054622d58b5c6af7. Report an issue: GitHub.