What causes "Invalid batch parameters buffer" in apache/shardingsphere?

Use a maintained client library to build the batch parameters block instead of hand-serializing clumplets.

apache/shardingsphere · error · FirebirdProtocolException

Invalid batch parameters buffer

Error message

Invalid batch parameters buffer

What it means

FirebirdProtocolException ('Invalid batch parameters buffer') from ensureClumpletHeaderReadable: while iterating the batch parameters clumplets, fewer than 5 bytes (1 tag byte + 4 little-endian length bytes) remain but the buffer still claims to be readable. The clumplet stream is truncated or malformed.

Source

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

                    // blobPolicy = BLOB_STREAM == requestedBlobPolicy ? requestedBlobPolicy : BLOB_STREAM;
                    // TODO Support BLOB policy after implementing the Firebird batch BLOB subprotocol.
                    throw new FirebirdProtocolException("BLOB policy is not supported in Firebird batch operations");
                } else {
                    reader.skipBytes(valueLength);
                }
            }
            // return new BatchParameters(version, bufferSize, recordCounts, multiError, blobPolicy);
            return new BatchParameters(version, bufferSize, recordCounts, multiError);
        }
        
        private static long getBufferSize(final int requestedBufferSize) {
            long result = Integer.toUnsignedLong(requestedBufferSize);
            return 0L == result ? MAX_BUFFER_SIZE : Math.min(result, MAX_BUFFER_SIZE);
        }
        
        private static void ensureClumpletHeaderReadable(final ByteBuf reader) {
            if (reader.readableBytes() < 1 + WIDE_CLUMPLET_LENGTH_SIZE) {
                throw new FirebirdProtocolException("Invalid batch parameters buffer");
            }
        }
        
        private static void ensureClumpletValueReadable(final ByteBuf reader, final int tag, final int valueLength) {
            if (valueLength < 0 || valueLength > reader.readableBytes()) {
                throw new FirebirdProtocolException("Invalid batch parameter length for tag %d: %d", tag, valueLength);
            }
        }
        
        private static int readIntegerValue(final ByteBuf reader, final int tag, final int valueLength) {
            if (INTEGER_VALUE_LENGTH != valueLength) {
                throw new FirebirdProtocolException("Invalid batch parameter integer length for tag %d: %d", tag, valueLength);
            }
            return reader.readIntLE();
        }
    }
}

View on GitHub (pinned to e952770a21)

Solutions

Use a maintained client library to build the batch parameters block instead of hand-serializing clumplets.
Verify each clumplet is exactly: 1 tag byte, 4-byte little-endian value length, then that many value bytes; ensure the buffer ends exactly at a clumplet boundary.
Check packet reassembly if the batch parameters span multiple network packets.

Defensive patterns

Strategy: try-catch

Try / catch

catch (SQLException e) {
    if (e.getMessage().contains("Invalid batch parameters buffer")) { throw new IllegalStateException("client clumplet encoding bug (truncated header)", e); }
    throw e;
}

Prevention

Format clumplets strictly as tag byte + 4-byte LE length + value.
End the buffer exactly on a clumplet boundary.

When it happens

Trigger: BatchParameters.parse() loop: reader.isReadable() is true but reader.readableBytes() < 1 + WIDE_CLUMPLET_LENGTH_SIZE (4). A tag was consumed or a length misread, leaving a partial header; or the client buffer was sliced at a wrong offset.

Common situations: hand-built batch parameters buffer with off-by-one length; client writing 2-byte clumplet lengths where the proxy expects 4-byte wide clumplets (batch blocks use wide lengths); buffer truncation from max-packet-size splitting.

Related errors

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