elastic/elasticsearch · error · IllegalArgumentException

VectorValuesField "{}" appears more than once in this docume

Error message

VectorValuesField "{}" appears more than once in this document (only one value is allowed per field)

What it means

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.

Source

Thrown at libs/gpu-codec/src/main/java/org/elasticsearch/gpu/codec/ES92GpuHnswVectorsWriter.java:891

        throw new IllegalArgumentException("invalid distance function: " + func);
    }

    private static class FieldWriter extends KnnFieldVectorsWriter<float[]> {
        private static final long SHALLOW_SIZE = RamUsageEstimator.shallowSizeOfInstance(FieldWriter.class);

        private final FieldInfo fieldInfo;
        private int lastDocID = -1;
        private final FlatFieldVectorsWriter<float[]> flatFieldVectorsWriter;

        FieldWriter(FlatFieldVectorsWriter<float[]> flatFieldVectorsWriter, FieldInfo fieldInfo) {
            this.fieldInfo = fieldInfo;
            this.flatFieldVectorsWriter = Objects.requireNonNull(flatFieldVectorsWriter);
        }

        @Override
        public void addValue(int docID, float[] vectorValue) throws IOException {
            if (docID == lastDocID) {
                throw new IllegalArgumentException(
                    "VectorValuesField \""
                        + fieldInfo.name
                        + "\" appears more than once in this document (only one value is allowed per field)"
                );
            }
            flatFieldVectorsWriter.addValue(docID, vectorValue);
            lastDocID = docID;
        }

        @Override
        public float[] copyValue(float[] vectorValue) {
            throw new UnsupportedOperationException();
        }

        @Override
        public long ramBytesUsed() {
            return SHALLOW_SIZE + flatFieldVectorsWriter.ramBytesUsed();
        }

View on GitHub (pinned to db6a809a66)

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.

Example fix

// before — document with duplicate vector field
// { "my_vector": [1.0, 2.0, 3.0], "my_vector": [4.0, 5.0, 6.0] }

// after — single vector per field
// { "my_vector": [1.0, 2.0, 3.0] }

Defensive patterns

Strategy: validation

Validate before calling

// Before indexing, check the document source does not have duplicate vector fields
JsonParser parser = document.getParser();
Set<String> seenVectorFields = new HashSet<>();
for (var field : document) {
    if (isVectorField(field) && !seenVectorFields.add(field.name())) {
        throw new IllegalArgumentException("Duplicate vector field: " + field.name());
    }
}

Try / catch

try {
    fieldWriter.addValue(docID, vectorValue);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("appears more than once")) {
        // log and handle duplicate vector value
    }
    throw e;
}

Prevention

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.

When it happens

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

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

Related errors

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