{"record":{"id":"8a73e106f4198838","repo":"elastic/elasticsearch","slug":"unsupported-query-index-bits-combination","errorCode":null,"errorMessage":"Unsupported query/index bits combination: {}/{}","messagePattern":"Unsupported query/index bits combination: (.+?)/(.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/simdvec/src/main/java/org/elasticsearch/simdvec/ES940OSQVectorsScorer.java","lineNumber":69,"sourceCode":"\n        QuantEncoding(byte indexBits, byte queryBits) {\n            this(indexBits, queryBits, BitEncoding.STRIPED);\n        }\n\n        QuantEncoding(byte indexBits, byte queryBits, BitEncoding bitEncoding) {\n            this.indexBits = indexBits;\n            this.queryBits = queryBits;\n            this.bitEncoding = bitEncoding;\n        }\n\n        public static QuantEncoding of(byte queryBits, byte indexBits, BitEncoding bitEncoding) {\n            return switch ((queryBits << 8) | indexBits) {\n                case (1 << 8) | 1 -> D1Q1;\n                case (4 << 8) | 1 -> D1Q4;\n                case (4 << 8) | 2 -> bitEncoding == BitEncoding.PACKED ? D2Q4_PACKED : D2Q4_STRIPED;\n                case (4 << 8) | 4 -> bitEncoding == BitEncoding.PACKED ? D4Q4_PACKED : D4Q4_STRIPED;\n                case (7 << 8) | 7 -> D7Q7;\n                default -> throw new IllegalArgumentException(\"Unsupported query/index bits combination: \" + queryBits + \"/\" + indexBits);\n            };\n        }\n\n        public byte indexBits() {\n            return indexBits;\n        }\n\n        public byte queryBits() {\n            return queryBits;\n        }\n\n        public BitEncoding bitEncoding() {\n            return bitEncoding;\n        }\n    }\n\n    protected static final float[] BIT_SCALES = new float[] {\n        1f,","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/simdvec/src/main/java/org/elasticsearch/simdvec/ES940OSQVectorsScorer.java#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use one of the supported combinations: query/index bits of (1,1), (1,4), (2,4), (4,4), or (7,7).","Ensure queryBits and indexBits are consistent with how the index was quantized — re-quantize the index if the bit widths must change.","Validate the pair at scorer-construction / config-load time and reject with a clear message listing supported pairs.","If a new combination is required, add a QuantEncoding enum constant and the corresponding scoring implementation + tests."],"exampleFix":"// before\nQuantEncoding.of(queryBits, indexBits, bitEncoding); // (3,3) -> throws\n\n// after: validate the supported set up front\nif (!Set.of(\"1/1\",\"1/4\",\"2/4\",\"4/4\",\"7/7\").contains(queryBits + \"/\" + indexBits)) {\n    throw new IllegalArgumentException(\"Unsupported OSQ query/index bits: \" + queryBits + \"/\" + indexBits);\n}\nQuantEncoding.of(queryBits, indexBits, bitEncoding);","handlingStrategy":"validation","validationCode":"private static final Set<String> SUPPORTED_PAIRS = Set.of(\"1/1\", \"1/4\", \"2/4\", \"4/4\", \"7/7\");\nString key = queryBits + \"/\" + indexBits;\nif (!SUPPORTED_PAIRS.contains(key)) {\n    throw new IllegalArgumentException(\"Unsupported OSQ query/index bits: \" + key + \"; supported: \" + SUPPORTED_PAIRS);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use a supported (queryBits,indexBits) pair.","Keep queryBits consistent with the index's quantization bits; re-quantize if they diverge.","Validate the pair at scorer construction and surface supported combinations."],"tags":["simdvec","quantization","scoring","vectors","osq"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}