dotnet/efcore · error · ArgumentException

The value '{value}' provided for argument '{argumentName}' m

Error message

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

What it means

IsVectorProperty validates the DistanceFunction argument with Enum.IsDefined. A DistanceFunction value that is not a defined enum member (e.g. (DistanceFunction)999 produced by an invalid cast or bad deserialization) fails the check and throws ArgumentException via CoreStrings.InvalidEnumValue. Defined members include Cosine, Euclidean, and DotProduct.

Source

Thrown at src/EFCore.Cosmos/Extensions/CosmosPropertyBuilderExtensions.cs:212

    /// <returns><see langword="true" /> if the vector distance function and dimensions can be set.</returns>
    public static bool CanSetIsVectorProperty(
        this IConventionPropertyBuilder propertyBuilder,
        DistanceFunction distanceFunction,
        int dimensions,
        bool fromDataAnnotation = false)
        => propertyBuilder.CanSetAnnotation(
                CosmosAnnotationNames.VectorDistanceFunction,
                ValidateVectorDistanceFunction(distanceFunction),
                fromDataAnnotation)
            && propertyBuilder.CanSetAnnotation(
                CosmosAnnotationNames.VectorDimensions,
                dimensions,
                fromDataAnnotation);

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

    /// <summary>
    ///     Configures this property to be the etag concurrency token.
    /// </summary>
    /// <remarks>
    ///     See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see>, and
    ///     <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information and examples.
    /// </remarks>
    /// <param name="propertyBuilder">The builder for the property being configured.</param>
    /// <returns>The same builder instance so that multiple calls can be chained.</returns>
    public static PropertyBuilder IsETagConcurrency(this PropertyBuilder propertyBuilder)
    {
        propertyBuilder
            .IsConcurrencyToken()

View on GitHub (pinned to dbf9771522)

Solutions

Use a named DistanceFunction member (DistanceFunction.Cosine, .Euclidean, or .DotProduct).
If the value originates from config/API input, validate it first with Enum.TryParse(typeof(DistanceFunction), value, out _) or Enum.IsDefined before passing.
Tighten the config schema to an enum/string so invalid values fail at load time.

Example fix

// before (invalid cast)
var df = (DistanceFunction)config.GetValue<int>("VectorDistance");
b.Property(x => x.Embedding).IsVectorProperty(df, 10);

// after (validate from config)
var raw = config["VectorDistance"];
if (!Enum.TryParse<DistanceFunction>(raw, out var df) || !Enum.IsDefined(df))
    throw new ConfigurationException($"Invalid VectorDistance '{raw}'");
b.Property(x => x.Embedding).IsVectorProperty(df, 10);

Defensive patterns

Strategy: validation

Validate before calling

// Validate the enum before configuring the property.
DistanceFunction df = /* from config */;
if (!Enum.IsDefined(df))
    throw new ArgumentException($"Invalid {nameof(DistanceFunction)} value: {df}");
b.Property(x => x.Embedding).IsVectorProperty(df, 10);

Type guard

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

Try / catch

try { b.Property(x => x.Embedding).IsVectorProperty(df, dims); }
catch (ArgumentException ex) when (ex.Message.Contains(nameof(DistanceFunction)))
{ throw new ConfigurationException($"Configure a valid DistanceFunction (Cosine/Euclidean/DotProduct).", ex); }

Prevention

Use named DistanceFunction members, never integer casts.
Validate external/config values with Enum.TryParse + Enum.IsDefined before passing.
Bind config to the enum type directly so invalid values fail at load.

When it happens

Trigger: Casting an arbitrary integer to DistanceFunction that is not a named member; deserializing a DistanceFunction from JSON/config whose value does not map to a defined name; passing default(DistanceFunction) cast through an untyped boundary.

Common situations: Reading distance function from a settings file with no schema validation; receiving the value over an API as an int; copy-paste of a numeric code that is out of range.

Related errors

AI-assisted analysis of dotnet/efcore@dbf9771522 (2026-08-06). Data as JSON: /api/errors/1b8e15c0f4593569. Report an issue: GitHub.