elastic/elasticsearch · error · IllegalArgumentException

beamWidth must be positive and less than or equal to 3200; b

Error message

beamWidth must be positive and less than or equal to 3200; beamWidth={}

What it means

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.

Source

Thrown at libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswSQVectorsFormat.java:90

    ES92GpuHnswSQVectorsFormat(
        Supplier<CuVSResourceManager> cuVSResourceManagerSupplier,
        long totalDeviceMemory,
        int maxConn,
        int beamWidth,
        Float confidenceInterval,
        int bits,
        boolean compress
    ) {
        super(NAME);
        this.totalDeviceMemory = totalDeviceMemory;
        this.cuVSResourceManagerSupplier = cuVSResourceManagerSupplier;
        if (maxConn <= 0 || maxConn > MAXIMUM_MAX_CONN) {
            throw new IllegalArgumentException(
                "maxConn must be positive and less than or equal to " + MAXIMUM_MAX_CONN + "; maxConn=" + maxConn
            );
        }
        if (beamWidth <= 0 || beamWidth > MAXIMUM_BEAM_WIDTH) {
            throw new IllegalArgumentException(
                "beamWidth must be positive and less than or equal to " + MAXIMUM_BEAM_WIDTH + "; beamWidth=" + beamWidth
            );
        }
        this.maxConn = maxConn;
        this.beamWidth = beamWidth;
        this.flatVectorsFormat = new ES814ScalarQuantizedVectorsFormat(confidenceInterval, bits, compress);
    }

    @Override
    public KnnVectorsWriter fieldsWriter(SegmentWriteState state) throws IOException {
        return new ES92GpuHnswVectorsWriter(
            cuVSResourceManagerSupplier.get(),
            totalDeviceMemory,
            state,
            maxConn,
            beamWidth,
            flatVectorsFormat,
            flatVectorsFormat.fieldsWriter(state)

View on GitHub (pinned to db6a809a66)

Solutions

1. Set beamWidth to a value in the range 1–3200; the default is derived from Lucene99HnswVectorsFormat defaults.
2. Ensure beamWidth is strictly greater than maxConn (CAGRA requires intermediateGraphDegree > graphDegree; the code enforces this internally via Math.max).
3. Use the no-arg constructor which uses safe defaults.

Example fix

// before
new ES92GpuHnswSQVectorsFormat(totalMem, maxConn, 5000, null, 7, false); // 5000 > 3200

// after
new ES92GpuHnswSQVectorsFormat(totalMem, maxConn, 200, null, 7, false); // valid range

if (beamWidth <= 0 || beamWidth > ES92GpuHnswSQVectorsFormat.MAXIMUM_BEAM_WIDTH) {
    throw new IllegalArgumentException("beamWidth must be in range [1, " + ES92GpuHnswSQVectorsFormat.MAXIMUM_BEAM_WIDTH + "], got: " + beamWidth);
}
new ES92GpuHnswSQVectorsFormat(totalDeviceMemory, maxConn, beamWidth, confidenceInterval, bits, compress);

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• maxConn must be positive and less than or equal to 512; maxC
• segment of size [{}] too small for expected {} float vectors
• negative number of vectors: {}
• negative vector dims: {}
• Field [{}] must have FLOAT32 encoding, got: {}

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