{"record":{"id":"054622d58b5c6af7","repo":"apache/shardingsphere","slug":"mysql-blob-type-meta-in-binlog-should-be-range-1-t","errorCode":null,"errorMessage":"MySQL BLOB type meta in binlog should be range 1 to 4, but actual value is: %s","messagePattern":"MySQL BLOB type meta in binlog should be range 1 to 4, but actual value is: (.+?)","errorType":"exception","errorClass":"UnsupportedSQLOperationException","httpStatus":null,"severity":"error","filePath":"database/protocol/dialect/mysql/src/main/java/org/apache/shardingsphere/database/protocol/mysql/packet/binlog/row/column/value/blob/MySQLBlobBinlogProtocolValue.java","lineNumber":48,"sourceCode":"public final class MySQLBlobBinlogProtocolValue implements MySQLBinlogProtocolValue {\n    \n    @Override\n    public Serializable read(final MySQLBinlogColumnDef columnDef, final MySQLPacketPayload payload) {\n        return payload.readStringFixByBytes(readLengthFromMeta(columnDef.getColumnMeta(), payload));\n    }\n    \n    private int readLengthFromMeta(final int columnMeta, final MySQLPacketPayload payload) {\n        switch (columnMeta) {\n            case 1:\n                return payload.getByteBuf().readUnsignedByte();\n            case 2:\n                return payload.getByteBuf().readUnsignedShortLE();\n            case 3:\n                return payload.getByteBuf().readUnsignedMediumLE();\n            case 4:\n                return payload.readInt4();\n            default:\n                throw new UnsupportedSQLOperationException(String.format(\"MySQL BLOB type meta in binlog should be range 1 to 4, but actual value is: %s\", columnMeta));\n        }\n    }\n}\n","sourceCodeStart":30,"sourceCodeEnd":52,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/database/protocol/dialect/mysql/src/main/java/org/apache/shardingsphere/database/protocol/mysql/packet/binlog/row/column/value/blob/MySQLBlobBinlogProtocolValue.java#L30-L52","documentation":"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.","triggerScenarios":"Calling readLengthFromMeta() with a columnMeta outside 1–4 while parsing a WRITE_ROWS/UPDATE_ROWS event for a BLOB/TEXT column in MySQLBlobBinlogProtocolValue.","commonSituations":"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.","solutions":["Confirm the MySQL server version producing the binlog is supported by the proxy's binlog parser","Dump the offending binlog event with mysqlbinlog --base64-output=DECODE-ROWS -vv and check the table map metadata for the BLOB column","Check whether the table schema changed (ALTER on the blob column) while events were being consumed, desyncing the table map cache","Report the column meta value and server version upstream so the case can be classified or supported"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before decoding a blob column from a row event, check the table-map meta\nint columnMeta = columnDefinition.getColumnMeta();\nif (columnMeta < 1 || columnMeta > 4) {\n    // stale/foreign TABLE_MAP: resubscribe or skip the event instead of throwing mid-decode\n    resyncFromCurrentPosition();\n    return;\n}","typeGuard":null,"tryCatchPattern":"try {\n    value = blobValue.read(columnMeta, payload);\n} catch (UnsupportedSQLOperationException ex) {\n    // unsupported blob meta width: skip this event, log the binlog position and server version,\n    // and resynchronize the table map cache before the next event\n    skipEventAndResync(eventHeader, ex);\n}","preventionTips":["Refresh TABLE_MAP metadata on every schema change (subscribe to query events or poll schema)","Verify server flavor/version is supported before enabling binlog ingestion"],"tags":["mysql","binlog","blob","cdc","metadata-mismatch"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}