dotnet/efcore · error · InvalidOperationException

The property '{propertyType} {structuralType}.{property}' ha

Error message

The property '{propertyType} {structuralType}.{property}' has element type '{elementType}', which requires a value converter. Elements types requiring value converters are not currently supported with the Azure Cosmos DB database provider.

What it means

Thrown by CosmosModelValidator.ValidateElementConverters while walking a property's element-type-mapping chain (typeMapping.ElementTypeMapping loop). Cosmos has no way to serialize element values that need a value converter (e.g. a custom struct element, an enum stored as a non-native type), so any converter in that chain is rejected. The message names the property CLR type, structural type, property name, and the element CLR type that carried the converter.

Source

Thrown at src/EFCore.Cosmos/Infrastructure/Internal/CosmosModelValidator.cs:713

    }

    /// <summary>
    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
    ///     any release. You should only use it directly in your code with extreme caution and knowing that
    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
    /// </summary>
    protected virtual void ValidateElementConverters(
        IProperty property,
        ITypeBase structuralType,
        IDiagnosticsLogger<DbLoggerCategory.Model.Validation> logger)
    {
        var typeMapping = property.GetElementType()?.GetTypeMapping();
        while (typeMapping != null)
        {
            if (typeMapping.Converter != null)
            {
                throw new InvalidOperationException(
                    CosmosStrings.ElementWithValueConverter(
                        property.ClrType.ShortDisplayName(),
                        structuralType.ShortName(),
                        property.Name,
                        typeMapping.ClrType.ShortDisplayName()));
            }

            typeMapping = typeMapping.ElementTypeMapping;
        }
    }

    /// <summary>
    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
    ///     any release. You should only use it directly in your code with extreme caution and knowing that
    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
    /// </summary>
    protected virtual void ValidateConcurrencyToken(

View on GitHub (pinned to dbf9771522)

Solutions

Remove the value converter from the element type, or change the element CLR type to a Cosmos-native type (string, int, bool, byte, sbyte, float, double, etc.).
If a custom type is required, project it into a separate owned/entity shape that Cosmos can serialize natively, instead of storing it as a converted array element.
Avoid registering the converter globally; scope it so it does not attach to collection elements.

Example fix

// before
modelBuilder.Entity<Order>()
    .Property(o => o.Tags)
    .HasConversion(
        v => string.Join('|', v),
        v => v.Split('|').ToList());

// after: store the collection as a native List<string> without an element converter
public List<string> Tags { get; set; }

Defensive patterns

Strategy: validation

Validate before calling

// Detect element converters on Cosmos-mapped collections before validation
foreach (var et in modelBuilder.Model.GetEntityTypes())
{
    foreach (var prop in et.GetProperties())
    {
        var el = prop.GetElementType();
        if (el?.GetTypeMapping()?.Converter is not null)
        {
            throw new InvalidOperationException($"Property {et.DisplayName()}.{prop.Name} has an element value converter, unsupported by Cosmos.");
        }
    }
}

Prevention

Avoid global value converters; scope them so they do not attach to collection elements.
Use native CLR element types (string, int, bool, byte, sbyte, float, double) for collections stored in Cosmos.

When it happens

Trigger: Declaring a collection property whose element type has a value converter configured, e.g. List<MyEnum> with a non-default enum conversion, or a List<Guid> with a custom converter applied at the element level. Also triggered by owned collections whose elements have converters.

Common situations: Reusing a relational model (which supports element converters) against the Cosmos provider. Custom value converters on enums or value objects that are applied globally and therefore also attach to collection elements.

Related errors

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