dotnet/efcore · error · ArgumentException

The value ' ' provided for argument ' ' must be a valid…

Error message

The value '{value}' provided for argument '{argumentName}' must be a valid value of enum type '{enumType}'.

What it means

The ValidateVectorDistanceFunction method in CosmosComplexCollectionTypePropertyBuilderExtensions checks that the provided DistanceFunction enum value is defined using Enum.IsDefined. If the value falls outside the defined enum range (e.g., a cast from an invalid integer), the method throws ArgumentException. This guards the IsVectorProperty configuration against undefined distance metrics for Cosmos vector search.

Solutions

Use a named DistanceFunction enum member: DistanceFunction.Cosine, DistanceFunction.DotProduct, or DistanceFunction.Euclidean.
If the value comes from external input, validate with Enum.IsDefined<DistanceFunction>(value) before passing it to IsVectorProperty.
Update the Microsoft.Azure.Cosmos package to ensure the enum definition matches expected values.

Example fix

// before — casting unchecked integer
var df = (DistanceFunction)configValue; // configValue could be 999
builder.IsVectorProperty(df, 1536);

// after — validate before use
var df = Enum.IsDefined<DistanceFunction>(configValue)
    ? (DistanceFunction)configValue
    : DistanceFunction.Cosine;
builder.IsVectorProperty(df, 1536);

Defensive patterns

Strategy: validation

Validate before calling

// Validate the enum before calling IsVectorProperty
DistanceFunction df = GetDistanceFunctionFromConfig();
if (!Enum.IsDefined(df))
{
    df = DistanceFunction.Cosine; // or throw
}
builder.IsVectorProperty(df, dimensions);

Type guard

static bool IsValidDistanceFunction(DistanceFunction df) => Enum.IsDefined(df);

Prevention

Use named enum members (DistanceFunction.Cosine, DotProduct, Euclidean) rather than integer casts.
Validate externally-sourced integer values with Enum.IsDefined<DistanceFunction> before casting.
Keep the Microsoft.Azure.Cosmos SDK version in sync with EF Core Cosmos package to avoid enum mismatches.

When it happens

Trigger: Calling IsVectorProperty((DistanceFunction)999, dimensions) or IsVectorProperty((DistanceFunction)(-1), dimensions) — passing an enum value that is not one of the defined members (Cosine, DotProduct, Euclidean). Can also occur if the enum value is cast from an external integer source without validation.

Common situations: Deserializing a DistanceFunction from user input or configuration that may contain invalid integer values; casting an integer to DistanceFunction without bounds checking; version mismatch where a newer SDK added enum values not present in the referenced version.

Related errors

AI-assisted analysis of dotnet/efcore@3a2006ef56 (2026-08-11). Data as JSON: /api/errors/70a7f6f1a4ef9362. Report an issue: GitHub.

Appendix: source

Thrown at src/EFCore.Cosmos/Extensions/CosmosComplexCollectionTypePropertyBuilderExtensions.cs:145

    ///     See <see href="https://aka.ms/efcore-docs-complex-types">Complex types</see>, and
    ///     <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information and examples.
    /// </remarks>
    /// <typeparam name="TProperty">The type of the property being configured.</typeparam>
    /// <param name="propertyBuilder">The builder for the property being configured.</param>
    /// <param name="distanceFunction">The distance function for a vector comparisons.</param>
    /// <param name="dimensions">The number of dimensions in the vector.</param>
    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
    public static ComplexCollectionTypePropertyBuilder<TProperty> IsVectorProperty<TProperty>(
        this ComplexCollectionTypePropertyBuilder<TProperty> propertyBuilder,
        DistanceFunction distanceFunction,
        int dimensions)
        => (ComplexCollectionTypePropertyBuilder<TProperty>)((ComplexCollectionTypePropertyBuilder)propertyBuilder).IsVectorProperty(
            distanceFunction, dimensions);

    private static DistanceFunction ValidateVectorDistanceFunction(DistanceFunction distanceFunction)
        => Enum.IsDefined(distanceFunction)
            ? distanceFunction
            : throw new ArgumentException(
                CoreStrings.InvalidEnumValue(
                    distanceFunction,
                    nameof(distanceFunction),
                    typeof(DistanceFunction)));
}

View on GitHub (pinned to 3a2006ef56)