{"record":{"id":"bdbb2506656d9a39","repo":"apache/shardingsphere","slug":"mysql-json-type-meta-in-binlog-should-be-range-1-t","errorCode":null,"errorMessage":"MySQL JSON type meta in binlog should be range 1 to 4, but actual value is: %s","messagePattern":"MySQL JSON 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/string/MySQLJsonBinlogProtocolValue.java","lineNumber":62,"sourceCode":"        try {\n            return MySQLJsonValueDecoder.decode(newlyByteBuf);\n        } finally {\n            newlyByteBuf.release();\n        }\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 JSON type meta in binlog should be range 1 to 4, but actual value is: %s\", columnMeta));\n        }\n    }\n}\n","sourceCodeStart":44,"sourceCodeEnd":66,"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/string/MySQLJsonBinlogProtocolValue.java#L44-L66","documentation":"Thrown while decoding a MySQL JSON column value from a binlog row event: the column metadata must be 1–4, selecting the width of the JSON payload length prefix (read as 1/2/3/4 bytes little-endian). Any other meta value throws UnsupportedSQLOperationException because the payload length cannot be located reliably.","triggerScenarios":"Calling readLengthFromMeta() with columnMeta outside 1–4 when parsing a row event's JSON column in MySQLJsonBinlogProtocolValue.","commonSituations":"Consuming binlogs from MySQL forks (MariaDB's JSON is really a LONGTEXT alias with different meta) or versions whose JSON binlog encoding differs; event reader desynchronized after a schema change.","solutions":["Verify the source server is MySQL (not MariaDB) at a supported version — MariaDB stores JSON differently and trips this check","Validate with mysqlbinlog that the JSON column's meta byte in the TABLE_MAP event is 1–4","Resync the binlog client from the current master status after schema changes to rebuild table metadata","If a legitimate new encoding exists, add the case to readLengthFromMeta() and contribute upstream"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"int meta = columnDefinition.getColumnMeta();\nif (columnDefinition.getType() == MYSQL_TYPE_JSON && (meta < 1 || meta > 4)) {\n    // likely MariaDB 'json' (LONGTEXT alias) or a stale table map: handle as text instead of decoding as MySQL JSON\n    decodeAsLongText(columnDefinition, payload);\n    return;\n}","typeGuard":null,"tryCatchPattern":"try {\n    value = jsonValue.read(meta, payload);\n} catch (UnsupportedSQLOperationException ex) {\n    // record position, classify server (MySQL vs MariaDB), then resync or fall back to text decoding\n    handleUnsupportedJsonMeta(eventHeader, meta, ex);\n}","preventionTips":["Detect server flavor at handshake and refuse or special-case MariaDB JSON columns","Rebuild table metadata after ALTER TABLE on tables containing JSON columns"],"tags":["mysql","binlog","json","cdc","metadata-mismatch"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}