{"record":{"id":"ae5d104cb5b80929","repo":"elastic/elasticsearch","slug":"maxconn-must-be-positive-and-less-than-or-equal-to","errorCode":null,"errorMessage":"maxConn must be positive and less than or equal to 512; maxConn={}","messagePattern":"maxConn must be positive and less than or equal to 512; maxConn=(.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswSQVectorsFormat.java","lineNumber":85,"sourceCode":"        boolean compress\n    ) {\n        this(CuVSResourceManager::pooling, totalDeviceMemory, maxConn, beamWidth, confidenceInterval, bits, compress);\n    }\n\n    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,","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswSQVectorsFormat.java#L67-L103","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set maxConn to a value in the range 1–512; the default is 16 (derived from Lucene99HnswVectorsFormat.DEFAULT_MAX_CONN).","If configuring via Elasticsearch index settings, set index.m to a valid value (typically 16–48 for dense vector search).","Use the no-arg constructor ES92GpuHnswSQVectorsFormat() which uses safe defaults."],"exampleFix":"// before\nnew ES92GpuHnswSQVectorsFormat(totalMem, 1024, beamWidth, null, 7, false); // 1024 > 512\n\n// after\nnew ES92GpuHnswSQVectorsFormat(totalMem, 48, beamWidth, null, 7, false); // valid range","handlingStrategy":"validation","validationCode":"if (maxConn <= 0 || maxConn > ES92GpuHnswSQVectorsFormat.MAXIMUM_MAX_CONN) {\n    throw new IllegalArgumentException(\"maxConn must be in range [1, \" + ES92GpuHnswSQVectorsFormat.MAXIMUM_MAX_CONN + \"], got: \" + maxConn);\n}\nnew ES92GpuHnswSQVectorsFormat(totalDeviceMemory, maxConn, beamWidth, confidenceInterval, bits, compress);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the no-arg constructor ES92GpuHnswSQVectorsFormat() for default safe values.","When customizing maxConn, keep it in the typical range of 16–48 for good recall/performance balance.","Validate user-provided index settings (index.m) against MAXIMUM_MAX_CONN (512) 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-12T13:17:24.610Z"}