What causes "Invalid batch parameter integer length for tag %d: %d" in apache/shardingsphere?

Encode every integer-valued batch parameter tag (multi-error, record counts, buffer bytes size) as exactly a 4-byte little-endian value with length field 4.

apache/shardingsphere · error · FirebirdProtocolException

Invalid batch parameter integer length for tag %d: %d

Error message

Invalid batch parameter integer length for tag %d: %d

What it means

FirebirdProtocolException from readIntegerValue: batch parameter tags that carry an integer value (TAG_MULTIERROR, TAG_RECORD_COUNTS, TAG_BUFFER_BYTES_SIZE) must declare exactly 4 value bytes (INTEGER_VALUE_LENGTH). Any other declared length is rejected before the value is read.

Source

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

            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

Encode every integer-valued batch parameter tag (multi-error, record counts, buffer bytes size) as exactly a 4-byte little-endian value with length field 4.
Do not compress boolean options to 1 byte; the protocol expects a full integer.
Use a reference client library implementation of the batch parameters block.

Defensive patterns

Strategy: try-catch

Try / catch

catch (SQLException e) {
    if (e.getMessage().contains("integer length for tag")) { throw new IllegalStateException("integer clumplet must be 4 bytes", e); }
    throw e;
}

Prevention

Encode integer-valued tags (multierror, record counts, buffer size) as exactly 4-byte LE values.
Do not compact booleans to 1 byte in the batch parameters block.

When it happens

Trigger: BatchParameters.parse() calls readIntegerValue(reader, tag, valueLength) for integer tags; valueLength != 4 throws 'Invalid batch parameter integer length for tag %d: %d'.

Common situations: a client encoding boolean flags as 1 byte instead of a 4-byte integer; a hand-rolled builder writing lengths in the wrong unit (e.g. bits or words); protocol-dialect confusion with older narrow clumplets.

Related errors

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