elastic/elasticsearch · error · IllegalArgumentException

maxConn must be positive and less than or equal to 512…

Error message

maxConn must be positive and less than or equal to 512; maxConn={}

What it means

Thrown by the ES92GpuHnswSQVectorsFormat constructor when maxConn (the HNSW graph degree — number of neighbors per node) is outside the valid range (0, 512]. The upper bound MAXIMUM_MAX_CONN (512) reflects CAGRA's limit on graph degree. This format builds the HNSW graph on GPU via Nvidia CAGRA and then writes it in Lucene99 format for CPU search.

Solutions

1. Set maxConn to a value in the range 1–512; the default is 16 (derived from Lucene99HnswVectorsFormat.DEFAULT_MAX_CONN).
2. If configuring via Elasticsearch index settings, set index.m to a valid value (typically 16–48 for dense vector search).
3. Use the no-arg constructor ES92GpuHnswSQVectorsFormat() which uses safe defaults.

Example fix

// before
new ES92GpuHnswSQVectorsFormat(totalMem, 1024, beamWidth, null, 7, false); // 1024 > 512

// after
new ES92GpuHnswSQVectorsFormat(totalMem, 48, beamWidth, null, 7, false); // valid range

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

When it happens

Trigger: Constructing ES92GpuHnswSQVectorsFormat with maxConn <= 0 or maxConn > 512. This happens when the index settings specify an out-of-range index.m or when a custom codec configuration passes invalid parameters. The format is typically instantiated by Elasticsearch's codec service based on index settings.

Common situations: User sets index.m (graph degree) to a value > 512 in the knn index settings; migrating from a non-GPU format where the maxConn limit is different (Lucene allows up to 512 as well, but some configs may use higher); programmatic codec construction with wrong constants.

Related errors

• beamWidth must be positive and less than or equal to 3200…
• attempt to retrieve score correction for different ord
• Field [ ] must have FLOAT32 encoding, got
• invalid distance function
• negative number of vectors

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

Appendix: source

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

        boolean compress
    ) {
        this(CuVSResourceManager::pooling, totalDeviceMemory, maxConn, beamWidth, confidenceInterval, bits, compress);
    }

    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,

View on GitHub (pinned to db6a809a66)