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

Thrown by ValidateVectorDistanceFunction when the DistanceFunction argument is not a defined enum value. The Cosmos vector indexing feature needs a concrete distance function, so an undefined/(int-cast) enum member is rejected at configuration time. Fires inside IsVectorProperty when building the Cosmos model.

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 dbf9771522)

Solutions

1. Pass a declared DistanceFunction member (e.g., DistanceFunction.Cosine, DotProduct, or Euclidean per the enum definition).
2. Validate external values with Enum.IsDefined(typeof(DistanceFunction), value) before passing them in.
3. If reading from config, map unknown values to a sensible default rather than casting blindly.

Example fix

// before
var df = (DistanceFunction)99;
propertyBuilder.IsVectorProperty(df, 1536); // throws

// after
var df = Enum.IsDefined(typeof(DistanceFunction), raw) ? (DistanceFunction)raw : DistanceFunction.Cosine;
propertyBuilder.IsVectorProperty(df, 1536);

if (!Enum.IsDefined(typeof(DistanceFunction), value))
{
    throw new ArgumentException($"{value} is not a valid DistanceFunction.", nameof(value));
}
propertyBuilder.IsVectorProperty(value, dimensions);

static bool IsValidDistanceFunction(DistanceFunction value)
    => Enum.IsDefined(typeof(DistanceFunction), value);

When it happens

Trigger: Calling propertyBuilder.IsVectorProperty((DistanceFunction)999, dimensions) or otherwise passing a DistanceFunction value not declared in the enum. Common when casting an arbitrary int to the enum or reading the value from unvalidated config.

Common situations: Casting an int from config/JSON into DistanceFunction without range-checking. Refactoring/renaming enum members and forgetting to update stored values. Defaulting an uninitialized enum field (value 0) when 0 is not a valid member.

Related errors

• Invalid number of index sort order values: {numValues} value
• The number argument cannot be a negative number.
• Cosmos-specific methods can only be used when the context is
• IsDescending and AllDescending cannot both be specified on t
• The type '{givenType}' cannot be mapped as a dictionary beca

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