litedb-org/LiteDB · error · ArgumentOutOfRangeException

Top-K must be greater than zero.

Error message

Top-K must be greater than zero.

What it means

Thrown by VectorTopKNear(BsonExpression, float[], int) when k <= 0. Top-K must request at least one result; a non-positive k is meaningless and is rejected before building the order clause. Note the validation runs after fieldExpr and target checks.

Source

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

        }

        internal ILiteQueryableResult<T> VectorTopKNear<K>(Expression<Func<T, K>> field, float[] target, int k)
        {
            var fieldExpr = _mapper.GetExpression(field);
            return this.VectorTopKNear(fieldExpr, target, k);
        }

        internal ILiteQueryableResult<T> VectorTopKNear(string field, float[] target, int k)
        {
            var fieldExpr = BsonExpression.Create($"$.{field}");
            return this.VectorTopKNear(fieldExpr, target, k);
        }

        internal ILiteQueryableResult<T> VectorTopKNear(BsonExpression fieldExpr, float[] target, int k)
        {
            if (fieldExpr == null) throw new ArgumentNullException(nameof(fieldExpr));
            if (target == null || target.Length == 0) throw new ArgumentException("Target vector must be provided.", nameof(target));
            if (k <= 0) throw new ArgumentOutOfRangeException(nameof(k), "Top-K must be greater than zero.");

            var targetArray = new BsonArray(target.Select(v => new BsonValue(v)));

            // Build VECTOR_SIM as order clause
            var simExpr = BsonExpression.Create($"VECTOR_SIM({fieldExpr.Source}, @0)", targetArray);

            _query.VectorField = fieldExpr.Source;
            _query.VectorTarget = target?.ToArray();
            _query.VectorMaxDistance = double.MaxValue;

            return this
                .OrderBy(simExpr, Query.Ascending)
                .Limit(k);
        }

        [Obsolete("Add `using LiteDB.Vector;` and call the LiteQueryableVectorExtensions.WhereNear extension instead.")]
        public ILiteQueryable<T> WhereNear(string vectorField, float[] target, double maxDistance)
        {

View on GitHub (pinned to f906a5f850)

Solutions

1. Clamp k to at least 1, e.g. var k = Math.Max(1, requestedK).
2. Validate the source of k (config, query string) before calling.
3. If k=0 legitimately means 'no results', short-circuit and return empty instead of calling the API.

Example fix

// before
var top = col.Query().VectorTopKNear("$.embedding", vec, requestedK).ToList();

// after
var k = Math.Max(1, requestedK);
var top = col.Query().VectorTopKNear("$.embedding", vec, k).ToList();

var k = Math.Max(1, requestedK);

static bool IsValidK(int k) => k > 0;

When it happens

Trigger: Calling VectorTopKNear(field, vec, 0), VectorTopKNear(field, vec, -5), or passing a k computed from a count that is zero (e.g. page size from config unset).

Common situations: Reading k from a config/pagination parameter defaulting to 0, computing k as resultsPerPage * (page-1) on page 1 with an off-by-one, or passing an unset int field.

Related errors

• Similarity threshold must be a valid number.
• Target vector must be provided.
• fieldExpr
• vectorField
• field

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