litedb-org/LiteDB · error · ArgumentException

Target vector must be provided.

Error message

Target vector must be provided.

What it means

Thrown by ValidateVectorArguments (called from CreateVectorSimilarityFilter, used by VectorWhereNear) when the target float[] is null or has zero length. A vector similarity query requires a concrete reference vector to compare stored embeddings against; an absent vector cannot produce distances.

Source

Thrown at LiteDB/Client/Database/LiteQueryable.cs:242

        {
            _query.Select = selector;

            return new LiteQueryable<BsonDocument>(_engine, _mapper, _collection, _query);
        }

        /// <summary>
        /// Project each document of resultset into a new document/value based on selector expression
        /// </summary>
        public ILiteQueryable<K> Select<K>(Expression<Func<T, K>> selector)
        {
            _query.Select = _mapper.GetExpression(selector);

            return new LiteQueryable<K>(_engine, _mapper, _collection, _query);
        }

        private static void ValidateVectorArguments(float[] target, double maxDistance)
        {
            if (target == null || target.Length == 0) throw new ArgumentException("Target vector must be provided.", nameof(target));
            // Dot-product queries interpret "maxDistance" as a minimum similarity score and may therefore pass negative values.
            if (double.IsNaN(maxDistance)) throw new ArgumentOutOfRangeException(nameof(maxDistance), "Similarity threshold must be a valid number.");
        }

        private static BsonExpression CreateVectorSimilarityFilter(BsonExpression fieldExpr, float[] target, double maxDistance)
        {
            if (fieldExpr == null) throw new ArgumentNullException(nameof(fieldExpr));

            ValidateVectorArguments(target, maxDistance);

            var targetArray = new BsonArray(target.Select(v => new BsonValue(v)));
            return BsonExpression.Create($"{fieldExpr.Source} VECTOR_SIM @0 <= @1", targetArray, new BsonValue(maxDistance));
        }

        internal ILiteQueryable<T> VectorWhereNear(string vectorField, float[] target, double maxDistance)
        {
            if (string.IsNullOrWhiteSpace(vectorField)) throw new ArgumentNullException(nameof(vectorField));

View on GitHub (pinned to f906a5f850)

Solutions

1. Ensure the embedding model returns a non-empty float[] before issuing the query.
2. Null/length-check the vector at the call site and short-circuit with a sensible default (e.g. skip the vector filter).
3. Verify the embedding dimension matches what was stored; an empty array often signals a truncated payload.

Example fix

// before
var results = col.Query().VectorWhereNear("$.embedding", embedding, 0.5).ToList();

// after
if (embedding == null || embedding.Length == 0)
    throw new InvalidOperationException("Embedding not available for this query.");
var results = col.Query().VectorWhereNear("$.embedding", embedding, 0.5).ToList();

if (target == null || target.Length == 0)
    throw new InvalidOperationException("A non-empty embedding vector is required.");

static bool IsValidVector(float[] v) => v != null && v.Length > 0;

When it happens

Trigger: Calling VectorWhereNear(field, null, maxDistance), VectorWhereNear(field, new float[0], maxDistance), or passing a vector that was not yet loaded from an embedding model. Reached via both the string-field and BsonExpression overloads.

Common situations: An embedding generation service returned null/empty, a deserialized vector array came back empty, or the embedding step was skipped for a query path. Also when wiring up an ANN search before embeddings are populated.

Related errors

• Similarity threshold must be a valid number.
• fieldExpr
• vectorField
• field
• Top-K must be greater than zero.

AI-assisted analysis of litedb-org/LiteDB@f906a5f850 (2026-08-13). Data as JSON: /api/errors/562173f05b6cf052. Report an issue: GitHub.