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.

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

• field
• fieldExpr
• field
• field
• Similarity threshold must be a valid number.

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

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