elastic/elasticsearch · error · IllegalArgumentException

Unsupported query/index bits combination: {}/{}

Error message

Unsupported query/index bits combination: {}/{}

What it means

Thrown by QuantEncoding.of(byte queryBits, byte indexBits, BitEncoding) when the (queryBits,indexBits) pair is not one of the supported OSQ quantization combinations: (1,1) D1Q1, (1,4) D1Q4, (2,4) D2Q4, (4,4) D4Q4, (7,7) D7Q7. Any other pair hits the default branch and raises IllegalArgumentException. The BitEncoding (PACKED vs STRIPED) only disambiguates the D2Q4/D4Q4 cases.

Source

Thrown at libs/simdvec/src/main/java/org/elasticsearch/simdvec/ES940OSQVectorsScorer.java:69

        QuantEncoding(byte indexBits, byte queryBits) {
            this(indexBits, queryBits, BitEncoding.STRIPED);
        }

        QuantEncoding(byte indexBits, byte queryBits, BitEncoding bitEncoding) {
            this.indexBits = indexBits;
            this.queryBits = queryBits;
            this.bitEncoding = bitEncoding;
        }

        public static QuantEncoding of(byte queryBits, byte indexBits, BitEncoding bitEncoding) {
            return switch ((queryBits << 8) | indexBits) {
                case (1 << 8) | 1 -> D1Q1;
                case (4 << 8) | 1 -> D1Q4;
                case (4 << 8) | 2 -> bitEncoding == BitEncoding.PACKED ? D2Q4_PACKED : D2Q4_STRIPED;
                case (4 << 8) | 4 -> bitEncoding == BitEncoding.PACKED ? D4Q4_PACKED : D4Q4_STRIPED;
                case (7 << 8) | 7 -> D7Q7;
                default -> throw new IllegalArgumentException("Unsupported query/index bits combination: " + queryBits + "/" + indexBits);
            };
        }

        public byte indexBits() {
            return indexBits;
        }

        public byte queryBits() {
            return queryBits;
        }

        public BitEncoding bitEncoding() {
            return bitEncoding;
        }
    }

    protected static final float[] BIT_SCALES = new float[] {
        1f,

View on GitHub (pinned to db6a809a66)

Solutions

1. Use one of the supported combinations: query/index bits of (1,1), (1,4), (2,4), (4,4), or (7,7).
2. Ensure queryBits and indexBits are consistent with how the index was quantized — re-quantize the index if the bit widths must change.
3. Validate the pair at scorer-construction / config-load time and reject with a clear message listing supported pairs.
4. If a new combination is required, add a QuantEncoding enum constant and the corresponding scoring implementation + tests.

Example fix

// before
QuantEncoding.of(queryBits, indexBits, bitEncoding); // (3,3) -> throws

// after: validate the supported set up front
if (!Set.of("1/1","1/4","2/4","4/4","7/7").contains(queryBits + "/" + indexBits)) {
    throw new IllegalArgumentException("Unsupported OSQ query/index bits: " + queryBits + "/" + indexBits);
}
QuantEncoding.of(queryBits, indexBits, bitEncoding);

private static final Set<String> SUPPORTED_PAIRS = Set.of("1/1", "1/4", "2/4", "4/4", "7/7");
String key = queryBits + "/" + indexBits;
if (!SUPPORTED_PAIRS.contains(key)) {
    throw new IllegalArgumentException("Unsupported OSQ query/index bits: " + key + "; supported: " + SUPPORTED_PAIRS);
}

When it happens

Trigger: Constructing an ES940OSQVectorsScorer with a (queryBits,indexBits) pair the scorer has no implementation for, e.g. (3,3), (4,2), (1,7); a config that sets mismatched query/index bit widths; a model trained with index bits that do not pair with the configured query bits.

Common situations: User-configured OSQ quantization with an unsupported combination; mismatched index_bits (from the stored index) and query_bits (from runtime config); newer quantization format with unimplemented scorer variants.

Related errors

• Unsupported bitsPerDim: {}
• vector dimensions incompatible: {}!= {}
• bit must be between 1 and 8, but was: {}
• attempt to retrieve score correction for different ord {} th

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/8a73e106f4198838. Report an issue: GitHub.