litedb-org/LiteDB · error · ArgumentNullException

fieldExpr

Error message

fieldExpr

What it means

Thrown by CreateVectorSimilarityFilter (the internal builder for VECTOR_SIM WHERE clauses) when fieldExpr is null. The field expression identifies which document field holds the stored vector; a null expression gives nothing to compare. Reached from VectorWhereNear(BsonExpression, ...).

Source

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

        /// 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));

            var fieldExpr = BsonExpression.Create($"$.{vectorField}");
            return this.VectorWhereNear(fieldExpr, target, maxDistance);
        }

        internal ILiteQueryable<T> VectorWhereNear(BsonExpression fieldExpr, float[] target, double maxDistance)
        {
            var filter = CreateVectorSimilarityFilter(fieldExpr, target, maxDistance);

View on GitHub (pinned to f906a5f850)

Solutions

1. Prefer the string overload VectorWhereNear(string vectorField, ...) which constructs the expression for you and validates the name.
2. Null-check the BsonExpression before calling and throw a clearer domain error.
3. Construct the expression via BsonExpression.Create($.{field}) only after validating the field name.

Example fix

// before
var q = col.Query().VectorWhereNear(fieldExpr, vec, dist);

// after
if (fieldExpr == null)
    throw new InvalidOperationException("Vector field expression is required.");
var q = col.Query().VectorWhereNear(fieldExpr, vec, dist);

if (fieldExpr == null)
    throw new InvalidOperationException("Vector field expression is required.");

When it happens

Trigger: Calling VectorWhereNear((BsonExpression)null, target, maxDistance), or passing a BsonExpression variable that resolved to null (e.g. a failed BsonExpression.Create whose result was discarded).

Common situations: Dynamically building the field expression and a branch returns null, or destructuring a config-driven field name that is empty so the created expression is discarded.

Related errors

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

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