apache/shardingsphere · error · UnsupportedSQLOperationException

MySQL Enum meta in binlog only include value 1 or 2, but act

Error message

MySQL Enum meta in binlog only include value 1 or 2, but actual is %s

What it means

Thrown while decoding a MySQL ENUM column from a binlog row event: ENUM storage meta must be 1 or 2 (byte or word index into the enum definition). Any other value throws UnsupportedSQLOperationException because the enum ordinal cannot be read.

Source

Thrown at database/protocol/dialect/mysql/src/main/java/org/apache/shardingsphere/database/protocol/mysql/packet/binlog/row/column/value/string/MySQLStringBinlogProtocolValue.java:65

            case STRING:
                return new MySQLBinaryString(payload.readStringFixByBytes(readActualLength(length, payload)));
            default:
                throw new UnsupportedSQLOperationException(MySQLBinaryColumnType.valueOf(type).toString());
        }
    }
    
    private int readActualLength(final int length, final MySQLPacketPayload payload) {
        return length < 256 ? payload.getByteBuf().readUnsignedByte() : payload.getByteBuf().readUnsignedShortLE();
    }
    
    private Serializable readEnumValue(final int meta, final MySQLPacketPayload payload) {
        switch (meta) {
            case 1:
                return payload.readInt1();
            case 2:
                return payload.readInt2();
            default:
                throw new UnsupportedSQLOperationException(String.format("MySQL Enum meta in binlog only include value 1 or 2, but actual is %s", meta));
        }
    }
}

View on GitHub (pinned to e952770a21)

Solutions

Decode the TABLE_MAP event for the table and confirm the column's real type/meta bytes match ENUM with width 1 or 2
Confirm the server flavor/version is MySQL with a supported binlog format (ROW)
Restart/resync the binlog subscription so table metadata is rebuilt from the current TABLE_MAP
Report the meta value and server version upstream if a genuine new encoding is found

Defensive patterns

Strategy: validation

Validate before calling

int meta = columnDefinition.getColumnMeta();
if (columnDefinition.isEnum() && meta != 1 && meta != 2) {
    // classification/meta mismatch: re-read the TABLE_MAP for this table before decoding enum columns
    refreshTableMap(event.getTableId());
    return;
}

Try / catch

try {
    value = readEnumValue(meta, payload);
} catch (UnsupportedSQLOperationException ex) {
    // enum width must be 1 or 2: log table id + meta, resync the table map, and skip the event
    resyncAndSkip(eventHeader, ex);
}

Prevention

Re-resolve TABLE_MAP entries after schema changes on enum-containing tables
Confirm MySQL vs MariaDB string-type encodings before ingesting mixed-fleet binlogs

When it happens

Trigger: Calling readEnumValue() with meta other than 1 or 2 when a row event's string column is classified as ENUM in MySQLStringBinlogProtocolValue.

Common situations: MariaDB/MySQL fork differences in string-type sub-encodings; a misread type byte (column classified as ENUM when it is SET or another string subtype) due to reader desync or a stale TABLE_MAP; enum columns after ALTER TABLE with many values.

Related errors

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