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

CosmosPropertyBuilderExtensions.ValidateVectorDistanceFunction throws ArgumentException(CoreStrings.InvalidEnumValue) when an undefined DistanceFunction enum value is passed to IsVectorProperty or CanSetIsVectorProperty. The check is Enum.IsDefined(distanceFunction); any value not declared on DistanceFunction (e.g. an explicit cast from an arbitrary int, or a future enum value removed after upgrade) is rejected at configuration time, before any annotation is set.

Solutions

Validate the value with Enum.IsDefined(typeof(DistanceFunction), value) before casting or calling IsVectorProperty, and fall back to a sensible default (e.g. DistanceFunction.Cosine) if it is not defined.
Bind configuration as a named string and parse with Enum.TryParse<DistanceFunction>(name, out var df) so unknown values are caught at parse time.
If upgrading EF Core, check the DistanceFunction members in the version you target and remap any removed value.
Avoid (DistanceFunction)someInt casts at call sites; route through a validation helper.

Example fix

// before - throws when cfg.DistanceFunctionInt is not a defined enum value
entityBuilder.Property(d => d.Embedding)
    .IsVectorProperty((DistanceFunction)cfg.DistanceFunctionInt, cfg.Dimensions);

// after - validate first
var df = Enum.IsDefined(typeof(DistanceFunction), cfg.DistanceFunctionInt)
    ? (DistanceFunction)cfg.DistanceFunctionInt
    : DistanceFunction.Cosine;
entityBuilder.Property(d => d.Embedding)
    .IsVectorProperty(df, cfg.Dimensions);

Defensive patterns

Strategy: validation

Validate before calling

// Validate the enum before configuring the vector property.
DistanceFunction SafeDistance(DistanceFunction df)
    => Enum.IsDefined(typeof(DistanceFunction), df)
        ? df
        : throw new ArgumentOutOfRangeException(nameof(df), df, "Undefined DistanceFunction value.");

builder.Property(d => d.Embedding).IsVectorProperty(SafeDistance(distanceFunction), dimensions);

Type guard

// If the value comes in as int from configuration, validate first.
static DistanceFunction ParseDistance(int raw, DistanceFunction fallback = DistanceFunction.Cosine)
    => Enum.IsDefined(typeof(DistanceFunction), raw) ? (DistanceFunction)raw : fallback;

Try / catch

try { builder.Property(d => d.Embedding).IsVectorProperty(df, dims); }
catch (ArgumentException ex) when (ex.Message.Contains("DistanceFunction"))
{ logger.InvalidDistanceFunction(df); /* fall back to a known good value */
  builder.Property(d => d.Embedding).IsVectorProperty(DistanceFunction.Cosine, dims); }

Prevention

Bind distance function from configuration by name, not by int cast.
Wrap int->enum casts with Enum.IsDefined at the boundary.
After upgrading EF Core, diff the DistanceFunction members against your stored values.
Keep a single SafeDistance(...) helper and use it everywhere.

When it happens

Trigger: Casting an arbitrary integer to DistanceFunction and passing it: builder.IsVectorProperty((DistanceFunction)42, 1536); reading a distance function from configuration as an int and casting without validation; downgrading EF Core where a DistanceFunction member was removed so a serialized value no longer maps to a defined member; passing default(DistanceFunction) when default is not a defined member.

Common situations: Loading distance function from a settings file as int and casting directly; sharing enums across versions; reflection-based model configuration that bypasses compile-time enum checks; upgrading EF Core and finding a previously-valid DistanceFunction value is no longer defined.

Related errors

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

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