{"record":{"id":"424cdeda71a62d4a","repo":"elastic/elasticsearch","slug":"beamwidth-must-be-positive-and-less-than-or-equal","errorCode":null,"errorMessage":"beamWidth must be positive and less than or equal to 3200; beamWidth={}","messagePattern":"beamWidth must be positive and less than or equal to 3200; beamWidth=(.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswSQVectorsFormat.java","lineNumber":90,"sourceCode":"    ES92GpuHnswSQVectorsFormat(\n        Supplier<CuVSResourceManager> cuVSResourceManagerSupplier,\n        long totalDeviceMemory,\n        int maxConn,\n        int beamWidth,\n        Float confidenceInterval,\n        int bits,\n        boolean compress\n    ) {\n        super(NAME);\n        this.totalDeviceMemory = totalDeviceMemory;\n        this.cuVSResourceManagerSupplier = cuVSResourceManagerSupplier;\n        if (maxConn <= 0 || maxConn > MAXIMUM_MAX_CONN) {\n            throw new IllegalArgumentException(\n                \"maxConn must be positive and less than or equal to \" + MAXIMUM_MAX_CONN + \"; maxConn=\" + maxConn\n            );\n        }\n        if (beamWidth <= 0 || beamWidth > MAXIMUM_BEAM_WIDTH) {\n            throw new IllegalArgumentException(\n                \"beamWidth must be positive and less than or equal to \" + MAXIMUM_BEAM_WIDTH + \"; beamWidth=\" + beamWidth\n            );\n        }\n        this.maxConn = maxConn;\n        this.beamWidth = beamWidth;\n        this.flatVectorsFormat = new ES814ScalarQuantizedVectorsFormat(confidenceInterval, bits, compress);\n    }\n\n    @Override\n    public KnnVectorsWriter fieldsWriter(SegmentWriteState state) throws IOException {\n        return new ES92GpuHnswVectorsWriter(\n            cuVSResourceManagerSupplier.get(),\n            totalDeviceMemory,\n            state,\n            maxConn,\n            beamWidth,\n            flatVectorsFormat,\n            flatVectorsFormat.fieldsWriter(state)","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswSQVectorsFormat.java#L72-L108","documentation":"Thrown by the ES92GpuHnswSQVectorsFormat constructor when beamWidth (the intermediate graph degree used during graph construction, before pruning) is outside the valid range (0, 3200]. The upper bound MAXIMUM_BEAM_WIDTH (3200) is a CAGRA constraint. This parameter controls the quality vs. build-time tradeoff of the GPU-built HNSW graph.","triggerScenarios":"Constructing ES92GpuHnswSQVectorsFormat with beamWidth <= 0 or beamWidth > 3200. This happens when index settings specify an out-of-range num_candidates/ef_construction equivalent or when programmatic codec configuration passes invalid values.","commonSituations":"User sets a high ef_construction or beam_width in index settings expecting better recall; migrating from a format with a different upper bound; passing the same value for maxConn and beamWidth when beamWidth must be strictly larger.","solutions":["Set beamWidth to a value in the range 1–3200; the default is derived from Lucene99HnswVectorsFormat defaults.","Ensure beamWidth is strictly greater than maxConn (CAGRA requires intermediateGraphDegree > graphDegree; the code enforces this internally via Math.max).","Use the no-arg constructor which uses safe defaults."],"exampleFix":"// before\nnew ES92GpuHnswSQVectorsFormat(totalMem, maxConn, 5000, null, 7, false); // 5000 > 3200\n\n// after\nnew ES92GpuHnswSQVectorsFormat(totalMem, maxConn, 200, null, 7, false); // valid range","handlingStrategy":"validation","validationCode":"if (beamWidth <= 0 || beamWidth > ES92GpuHnswSQVectorsFormat.MAXIMUM_BEAM_WIDTH) {\n    throw new IllegalArgumentException(\"beamWidth must be in range [1, \" + ES92GpuHnswSQVectorsFormat.MAXIMUM_BEAM_WIDTH + \"], got: \" + beamWidth);\n}\nnew ES92GpuHnswSQVectorsFormat(totalDeviceMemory, maxConn, beamWidth, confidenceInterval, bits, compress);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the no-arg constructor for safe defaults.","Ensure beamWidth is greater than maxConn (CAGRA requires intermediateGraphDegree > graphDegree).","Validate user-provided index settings against MAXIMUM_BEAM_WIDTH (3200) before constructing the format."],"tags":["gpu-codec","vector-search","validation","hnsw","configuration"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}