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, ...).

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

• field
• vectorField
• Similarity threshold must be a valid number.
• Target vector must be provided.
• 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.

Appendix: 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)