apache/shardingsphere · error · InvalidBatchParameterVersionException

Wrong version of batch parameters block %d, should be %d

Error message

Wrong version of batch parameters block %d, should be %d

What it means

InvalidBatchParameterVersionException thrown while parsing the batch parameters clumplet buffer: the first byte is the batch block version and only BATCH_VERSION_1 is accepted. A different first byte means the client speaks a newer (or corrupted) batch parameters layout the proxy cannot parse.

Source

Thrown at proxy/frontend/dialect/firebird/src/main/java/org/apache/shardingsphere/proxy/frontend/firebird/command/query/batch/FirebirdBatchCreateCommandExecutor.java:121

        private final int version;
        
        private final long bufferSize;
        
        private final boolean recordCounts;
        
        private final boolean multiError;
        
        // private final int blobPolicy;
        
        static BatchParameters parse(final ByteBuf batchParametersBuffer) {
            if (null == batchParametersBuffer || !batchParametersBuffer.isReadable()) {
                // return new BatchParameters(BATCH_VERSION_1, DEFAULT_BUFFER_SIZE, false, false, BLOB_STREAM);
                return new BatchParameters(BATCH_VERSION_1, DEFAULT_BUFFER_SIZE, false, false);
            }
            ByteBuf reader = batchParametersBuffer.duplicate();
            int version = reader.readUnsignedByte();
            if (BATCH_VERSION_1 != version) {
                throw new InvalidBatchParameterVersionException(version, BATCH_VERSION_1);
            }
            long bufferSize = DEFAULT_BUFFER_SIZE;
            boolean recordCounts = false;
            boolean multiError = false;
            // int blobPolicy = BLOB_STREAM;
            while (reader.isReadable()) {
                ensureClumpletHeaderReadable(reader);
                int tag = reader.readUnsignedByte();
                int valueLength = reader.readIntLE();
                ensureClumpletValueReadable(reader, tag, valueLength);
                if (TAG_MULTIERROR == tag) {
                    multiError = 0 != readIntegerValue(reader, tag, valueLength);
                } else if (TAG_RECORD_COUNTS == tag) {
                    recordCounts = 0 != readIntegerValue(reader, tag, valueLength);
                } else if (TAG_BUFFER_BYTES_SIZE == tag) {
                    bufferSize = getBufferSize(readIntegerValue(reader, tag, valueLength));
                } else if (TAG_BLOB_POLICY == tag) {
                    // int requestedBlobPolicy = readIntegerValue(reader, tag, valueLength);

View on GitHub (pinned to e952770a21)

Solutions

1. Pin the client to Firebird wire/batch protocol version 1 (e.g. Jaybird default for protocol 13 batches).
2. If implementing the wire protocol, ensure the batch parameters clumplet starts with the version byte 1 followed by tag clumplets (tag byte + 4-byte little-endian length + value).
3. Upgrade the ShardingSphere proxy to a version that supports the newer batch parameters version if your client requires it.

catch (SQLException e) {
    if (e.getMessage().contains("Wrong version of batch parameters")) {
        // downgrade: send an empty/default batch parameters block (version 1 semantics)
        sendCreateBatchWithDefaultParams(stmtHandle);
    } else throw e;
}

When it happens

Trigger: BatchParameters.parse() reads reader.readUnsignedByte() from a readable batch parameters buffer and compares against BATCH_VERSION_1; any other value (e.g. version 2 from a newer Firebird wire protocol) throws.

Common situations: a client built against Firebird 5 batch implementation details connecting to a proxy that only implements version 1; a packet builder that omits or shifts the version byte, making the next byte be read as the version; partial buffer truncation.

Related errors

• Invalid batch parameters buffer
• Invalid batch parameter length for tag %d: %d
• Invalid batch parameter integer length for tag %d: %d
• invalid message length: computed %d from BLR but client sent
• Can not locate agent jar file by URL `%s`.

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