{"record":{"id":"5c967fcda8a1a7a9","repo":"elastic/elasticsearch","slug":"vectorvaluesfield-appears-more-than-once-in-t","errorCode":null,"errorMessage":"VectorValuesField \"{}\" appears more than once in this document (only one value is allowed per field)","messagePattern":"VectorValuesField \"(.+?)\" appears more than once in this document \\(only one value is allowed per field\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswVectorsWriter.java","lineNumber":891,"sourceCode":"        throw new IllegalArgumentException(\"invalid distance function: \" + func);\n    }\n\n    private static class FieldWriter extends KnnFieldVectorsWriter<float[]> {\n        private static final long SHALLOW_SIZE = RamUsageEstimator.shallowSizeOfInstance(FieldWriter.class);\n\n        private final FieldInfo fieldInfo;\n        private int lastDocID = -1;\n        private final FlatFieldVectorsWriter<float[]> flatFieldVectorsWriter;\n\n        FieldWriter(FlatFieldVectorsWriter<float[]> flatFieldVectorsWriter, FieldInfo fieldInfo) {\n            this.fieldInfo = fieldInfo;\n            this.flatFieldVectorsWriter = Objects.requireNonNull(flatFieldVectorsWriter);\n        }\n\n        @Override\n        public void addValue(int docID, float[] vectorValue) throws IOException {\n            if (docID == lastDocID) {\n                throw new IllegalArgumentException(\n                    \"VectorValuesField \\\"\"\n                        + fieldInfo.name\n                        + \"\\\" appears more than once in this document (only one value is allowed per field)\"\n                );\n            }\n            flatFieldVectorsWriter.addValue(docID, vectorValue);\n            lastDocID = docID;\n        }\n\n        @Override\n        public float[] copyValue(float[] vectorValue) {\n            throw new UnsupportedOperationException();\n        }\n\n        @Override\n        public long ramBytesUsed() {\n            return SHALLOW_SIZE + flatFieldVectorsWriter.ramBytesUsed();\n        }","sourceCodeStart":873,"sourceCodeEnd":909,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswVectorsWriter.java#L873-L909","documentation":"Thrown by FieldWriter.addValue() when addValue is called twice for the same document ID. The GPU HNSW writer tracks lastDocID and rejects duplicate vector values for a single document — each document can have at most one vector per field. This mirrors Lucene's standard behavior for KnnVectorValues fields.","triggerScenarios":"Indexing a document that has two or more vector values for the same dense_vector field within a single document. This happens when the document source contains an array of vectors for a field that expects a single vector, or when the same field name is used twice in the document.","commonSituations":"Document JSON contains an array of vectors for a single dense_vector field (e.g. \"my_vector\": [ [1,2,3], [4,5,6] ]); client bug sending duplicate field values; ingest pipeline that duplicates vector fields; mapping change from multi-valued to single-valued without reindexing.","solutions":["Ensure each document has exactly one vector value per dense_vector field.","If multiple vectors per document are needed, use a different index design (e.g. nested documents or multiple named fields).","Fix the client/ingest pipeline to not send duplicate vector values for the same document.","Validate documents before indexing: check that dense_vector fields appear only once per document."],"exampleFix":"// before — document with duplicate vector field\n// { \"my_vector\": [1.0, 2.0, 3.0], \"my_vector\": [4.0, 5.0, 6.0] }\n\n// after — single vector per field\n// { \"my_vector\": [1.0, 2.0, 3.0] }","handlingStrategy":"validation","validationCode":"// Before indexing, check the document source does not have duplicate vector fields\nJsonParser parser = document.getParser();\nSet<String> seenVectorFields = new HashSet<>();\nfor (var field : document) {\n    if (isVectorField(field) && !seenVectorFields.add(field.name())) {\n        throw new IllegalArgumentException(\"Duplicate vector field: \" + field.name());\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    fieldWriter.addValue(docID, vectorValue);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"appears more than once\")) {\n        // log and handle duplicate vector value\n    }\n    throw e;\n}","preventionTips":["Ensure each document has at most one vector value per dense_vector field.","Validate documents on the client side before sending to Elasticsearch.","Use ingest pipelines to deduplicate or reject documents with multiple vector values."],"tags":["gpu-codec","vector-search","validation","duplicate-value","indexing"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}