apache/seatunnel · error · IllegalArgumentException

Sparse vector key must be Integer, but got: %s,

Error message

Sparse vector key must be Integer, but got: %s,

What it means

VectorUtils.convertSparseVectorToFloatArray requires sparse vector keys to be Integer indexes. When a map key is any other type it throws IllegalArgumentException 'Sparse vector key must be Integer, but got: <class name>'. The raw key class name is included in the message for diagnosis.

Source

Thrown at seatunnel-common/src/main/java/org/apache/seatunnel/common/utils/VectorUtils.java:141

    public static Integer[] toIntArray(ByteBuffer byteBuffer) {
        Integer[] intArray = new Integer[byteBuffer.capacity() / 4];

        for (int i = 0; i < intArray.length; i++) {
            intArray[i] = byteBuffer.getInt();
        }

        return intArray;
    }

    public static Float[] convertSparseVectorToFloatArray(Map<?, ?> sparseVector) {
        if (sparseVector.isEmpty()) {
            return new Float[0];
        }
        int maxIndex = -1;
        for (Map.Entry<?, ?> entry : sparseVector.entrySet()) {
            Object key = entry.getKey();
            if (!(key instanceof Integer)) {
                throw new IllegalArgumentException(
                        String.format(
                                "Sparse vector key must be Integer, but got: %s,",
                                key.getClass().getName()));
            }
            int index = (Integer) key;
            if (index < 0) {
                throw new IllegalArgumentException(
                        String.format("Sparse vector index cannot be negative: %d", index));
            }
            // prevent OOM
            if (index > 1000000) {
                throw new IllegalArgumentException(
                        String.format("Sparse vector index too large: %d", index));
            }
            maxIndex = Math.max(maxIndex, index);
        }
        Float[] denseVector = new Float[maxIndex + 1];
        Arrays.fill(denseVector, 0.0f);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Convert keys to Integer before calling: map.entrySet -> Integer.valueOf(key.toString())
2. Ensure JSON parsing produces Integer keys (use a typed Map<Integer, Float> target or custom deserializer)
3. Fix upstream producers to emit integer keys
4. Validate key types in a pre-check loop and coerce or reject early with a clearer error

Example fix

// before
Map<String, Float> sparse = parseJson(json); // keys are Strings
float[] arr = VectorUtils.convertSparseVectorToFloatArray(sparse);
// after
Map<Integer, Float> sparse = new HashMap<>();
parseJson(json).forEach((k, v) -> sparse.put(Integer.valueOf(k), v));
float[] arr = VectorUtils.convertSparseVectorToFloatArray(sparse);

boolean validSparseKeys(Map<?, ?> m) {
  return m.keySet().stream().allMatch(k -> k instanceof Integer && (Integer) k >= 0);
}
if (!validSparseKeys(sparseVector)) { throw new IllegalArgumentException("sparse keys must be non-negative Integers"); }

Map<Integer, Float> asIntegerKeyed(Map<?, ?> m) {
  Map<Integer, Float> out = new java.util.HashMap<>();
  m.forEach((k, v) -> out.put(Integer.valueOf(k.toString()), ((Number) v).floatValue()));
  return out;
}

try {
  return VectorUtils.convertSparseVectorToFloatArray(sparse);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Bad sparse vector input: " + e.getMessage(), e);
}

When it happens

Trigger: Passing a Map<?, ?> representing a sparse vector whose keys are e.g. String ("0", "1"), Long, or Double instead of Integer — usually from JSON deserialization producing String or Long keys, or a user-built map with the wrong key type.

Common situations: JSON payloads like {"0": 1.5} deserialized to Map<String, Object>; config/transform inputs where keys were read as Long from a numeric parser; mixing dense/sparse helper APIs with differently-typed maps.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Sparse vector value must be a Number, but got: %s
• Sparse vector index too large: %d
• Unsupported convert %s to Map, typeDefine: %s
• Unsupported convert %s to Array, typeDefine: %s
• Unsupported convert ${value.getClass()} to Row, typeDefine:

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/2e938c845dad8109. Report an issue: GitHub.