litedb-org/LiteDB · error · ArgumentOutOfRangeException

Dimensions must be greater than zero.

Error message

Dimensions must be greater than zero.

What it means

Thrown by the VectorIndexOptions constructor when dimensions is 0. A vector index requires a positive, fixed dimensionality to allocate storage and compute distances; zero is meaningless and would corrupt index geometry.

Source

Thrown at LiteDB/Client/Vector/VectorIndexOptions.cs:24

    /// Options used when creating a vector-aware index.
    /// </summary>
    public sealed class VectorIndexOptions
    {
        /// <summary>
        /// Gets the expected dimensionality of the indexed vectors.
        /// </summary>
        public ushort Dimensions { get; }

        /// <summary>
        /// Gets the distance metric used when comparing vectors.
        /// </summary>
        public VectorDistanceMetric Metric { get; }

        public VectorIndexOptions(ushort dimensions, VectorDistanceMetric metric = VectorDistanceMetric.Cosine)
        {
            if (dimensions == 0)
            {
                throw new ArgumentOutOfRangeException(nameof(dimensions), dimensions, "Dimensions must be greater than zero.");
            }

            this.Dimensions = dimensions;
            this.Metric = metric;
        }
    }
}

View on GitHub (pinned to f906a5f850)

Solutions

1. Compute dimensions from the actual embedding model output length and assert it is > 0 before constructing options.
2. Validate config-sourced dimensions against a positive bound at startup.
3. Default to the model's known dimension (e.g., 1536) rather than 0.

Example fix

// before
var opts = new VectorIndexOptions((ushort)dims, VectorDistanceMetric.Cosine);

// after
if (dims <= 0)
    throw new InvalidOperationException($"Invalid vector dimensions: {dims}");
var opts = new VectorIndexOptions((ushort)dims, VectorDistanceMetric.Cosine);

if (dimensions <= 0)
    throw new InvalidOperationException($"Invalid vector dimensions: {dimensions}");
var opts = new VectorIndexOptions((ushort)dimensions, metric);

static bool IsValidDimensions(int d) => d > 0 && d <= ushort.MaxValue;

When it happens

Trigger: Constructing new VectorIndexOptions(0); passing a dimensions value read from config that defaulted to 0; deriving dimensions from an empty or uninitialized embedding vector.

Common situations: Loading dimension count from appsettings where the key is missing (defaulting to 0); creating options before the embedding model is selected; off-by-one or unset ushort fields.

Related errors

• Value cannot be null. (Parameter 'collection')
• Vector index operations require LiteDB's default collection
• Value cannot be null. (Parameter 'source')
• Vector operations require LiteDB's default queryable impleme
• Value cannot be null. (Parameter 'repository')

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