fix(client-v2): reject non-array/non-List QBit write values

A non-null QBit value that is neither a Java array nor a List fell through
serializeQBitData to serializeArrayData, which writes no bytes for such a
value, desynchronizing the RowBinary stream so the following columns are
misread or rejected by the server. Reject it up-front with a clear
IllegalArgumentException, consistent with the existing fixed-dimension
validation and the Geometry reject-unsupported path.

Addresses Cursor Bugbot review on #2939.

Author: polyglotAI-bot

client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/SerializerUtils.java

@@ -480,18 +480,25 @@ public static void serializeArrayData(OutputStream stream, Object value, ClickHo
      * count is validated up-front so a wrong-sized (including empty) vector fails fast on the client
      * with a clear message instead of a late server {@code SERIALIZATION_ERROR}, mirroring the
      * client-side length enforcement already applied to the other fixed-size type,
-     * {@code FixedString(N)}.
+     * {@code FixedString(N)}. A non-null value that is neither a Java array nor a {@code List} cannot
+     * carry a vector and is rejected as well — otherwise it would fall through to
+     * {@link #serializeArrayData} and write no bytes for the column, desynchronizing the
+     * {@code RowBinary} stream and corrupting the columns that follow.
      */
     private static void serializeQBitData(OutputStream stream, Object value, ClickHouseColumn column) throws IOException {
         if (value != null) {
-            int length = -1;
+            int length;
             if (value.getClass().isArray()) {
                 length = Array.getLength(value);
             } else if (value instanceof List) {
                 length = ((List<?>) value).size();
+            } else {
+                throw new IllegalArgumentException("QBit column '" + column.getColumnName()
+                        + "' expects a Java array or List of its element type but got "
+                        + value.getClass().getName());
             }
             int dimension = column.getPrecision();
-            if (length >= 0 && length != dimension) {
+            if (length != dimension) {
                 throw new IllegalArgumentException("QBit column '" + column.getColumnName()
                         + "' expects exactly " + dimension + " elements but got " + length);
             }

client-v2/src/test/java/com/clickhouse/client/api/data_formats/internal/SerializerUtilsTest.java

@@ -170,6 +170,35 @@ private Object[][] qbitWrongDimension() {
         };
     }
 
+    @Test(dataProvider = "qbitWrongType")
+    public void testQBitSerializationRejectsNonArrayValue(Object value) {
+        // A non-null QBit value that is neither a Java array nor a List cannot carry a vector. It must
+        // be rejected up-front: otherwise it falls through to the Array serializer, which writes no
+        // bytes for the column, desynchronizing the RowBinary stream and corrupting the following
+        // columns. Writing into a byte sink so any (wrongly) emitted payload would be observable.
+        ClickHouseColumn column = ClickHouseColumn.of("vec", "QBit(Float32, 8)");
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+
+        IllegalArgumentException ex = Assert.expectThrows(IllegalArgumentException.class,
+                () -> SerializerUtils.serializeData(out, value, column));
+        Assert.assertTrue(ex.getMessage().contains("vec"),
+                "Message should name the column: " + ex.getMessage());
+        Assert.assertEquals(out.size(), 0,
+                "Nothing should be written to the stream when the value is rejected");
+    }
+
+    @DataProvider(name = "qbitWrongType")
+    private Object[][] qbitWrongType() {
+        // Values that are neither a Java array nor a List: a String, boxed scalars of the element
+        // type, and a Map. None of these can represent a QBit(E, N) vector.
+        return new Object[][] {
+                {"not-a-vector"},
+                {3.14f},
+                {42d},
+                {newMap("k", "v")},
+        };
+    }
+
     @Test
     public void testQBitSerializationAcceptsExactDimensionAndMatchesArray() throws Exception {
         float[] vec = {1f, -2f, 3.5f, 4f, 5f, 6f, 7f, 8f};

docs/features.md

@@ -44,7 +44,7 @@ Compatibility-sensitive traits:
 - Identifier quoting behavior is stable API for helper callers: identifiers are double-quoted, embedded double quotes are doubled, and optional quoting keeps simple identifiers unchanged.
 - Instant formatting is type-sensitive and should not drift: `Date` formatting depends on an explicit timezone, `DateTime` is serialized as epoch seconds, and higher-precision timestamps preserve up to 9 fractional digits.
 - `BFloat16` conversion is precision-sensitive and should not drift: a write keeps only the high 16 bits of the `float` (the low mantissa bits are truncated toward zero, matching the server's `Float32` → `BFloat16` conversion), so values that are not exactly representable in `BFloat16` change when written; a read widens the 16-bit value back to `float` losslessly.
-- `QBit` is wire-compatible with `Array(element_type)` and should not drift: the client transmits the logical vector as a length-prefixed array of its element type (`float[]` for `BFloat16`/`Float32`, `double[]` for `Float64`) rather than the server's bit-transposed on-disk layout, so a `QBit(E, N)` value read from or written to the server round-trips as an array of `E`. A written `QBit(E, N)` value must contain exactly `N` elements: a wrong-sized (including empty) vector is rejected during binary serialization with an `IllegalArgumentException` rather than deferred to a server error, matching the fixed dimension the server enforces.
+- `QBit` is wire-compatible with `Array(element_type)` and should not drift: the client transmits the logical vector as a length-prefixed array of its element type (`float[]` for `BFloat16`/`Float32`, `double[]` for `Float64`) rather than the server's bit-transposed on-disk layout, so a `QBit(E, N)` value read from or written to the server round-trips as an array of `E`. A written `QBit(E, N)` value must be a Java array or `List` holding exactly `N` elements: a wrong-sized (including empty) vector, or a non-null value that is neither an array nor a `List`, is rejected during binary serialization with an `IllegalArgumentException` rather than deferred to a server error or silently writing a misaligned stream, matching the fixed dimension the server enforces.
 - Timezone conversion helpers preserve nanoseconds and can intentionally shift local date or time when interpreted in a different timezone; this behavior is covered by tests and should not be normalized away.
 - `Geometry` handling is shape-sensitive: supported values are 1D through 4D Java arrays representing the nested geometry variants, and unsupported shapes or non-array values are rejected during serialization.
 - `Geometry` write inference is dimension-based rather than fully type-specific: point, ring/line string, polygon/multi-line string, and multi-polygon are selected from array depth, so writing `Geometry` cannot currently distinguish `Ring` from `LineString` or `Polygon` from `MultiLineString`.