litedb-org/LiteDB · error · ArgumentNullException

vectorField

Error message

vectorField

What it means

Thrown by VectorWhereNear(string vectorField, ...) when vectorField is null, empty, or whitespace. The string is used to build the field path $.{vectorField}; a blank name yields an invalid path. This is the friendly string overload that delegates to the BsonExpression version.

Source

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

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

            _query.Where.Add(filter);

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

            return this;
        }

View on GitHub (pinned to f906a5f850)

Solutions

1. Validate the field name with string.IsNullOrWhiteSpace at the call site.
2. Use a constant for the embedding field name to avoid typos and empty strings.
3. Cross-check the field name against the schema used when documents were inserted.

Example fix

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

// after
const string EmbeddingField = "embedding";
if (string.IsNullOrWhiteSpace(fieldName))
    fieldName = EmbeddingField;
var q = col.Query().VectorWhereNear(fieldName, vec, dist);

if (string.IsNullOrWhiteSpace(vectorField))
    throw new ArgumentException("Vector field name is required.", nameof(vectorField));

static bool IsValidFieldName(string s) => !string.IsNullOrWhiteSpace(s);

When it happens

Trigger: Calling VectorWhereNear("", vec, dist), VectorWhereNear(null, vec, dist), or VectorWhereNear(" ", vec, dist). Also when the field name comes from a config variable that is unset.

Common situations: Hardcoding a field name that was later renamed, reading the field name from configuration that is missing, or passing a property name constant that resolved to empty.

Related errors

• fieldExpr
• 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/4797efb808c3a96c. Report an issue: GitHub.