dotnet/efcore · error · InvalidOperationException

The property ' . ' has element type ' ', which requires a…

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 when walking the element-type mapping chain of a property (e.g. collections like List<T>) and finding a non-null Converter. The Cosmos provider cannot serialize element types that require value converters, so any converter in the element mapping chain is rejected.

Solutions

1. Use an element type Cosmos serializes natively (string, int, long, bool, double, DateTime in UTC, etc.). For enums store the underlying primitive and convert at the property/application level.
2. Move the conversion off the element: store a List<string> and parse in a wrapper property or backing field.
3. If you need a complex element, model it as an owned/embedded entity instead of a primitive collection.

Example fix

// before
public class Doc { public List<MyEnum> Flags { get; set; } }  // MyEnum needs a converter
modelBuilder.Entity<Doc>().Property(d => d.Flags)
          .ElementType().HasConversion(v => (int)v, v => (MyEnum)v);

// after
public class Doc { public List<int> Flags { get; set; } }   // store natively
// convert MyEnum <-> int in your code

// Flag any property whose element mapping chain contains a converter.
foreach (var et in modelBuilder.Model.GetEntityTypes())
foreach (var p in et.GetProperties())
    for (var m = p.GetElementType()?.GetTypeMapping(); m is not null; m = m.ElementTypeMapping)
        if (m.Converter is not null)
            throw new InvalidOperationException($"Element of {et.DisplayName()}.{p.Name} has a converter; use a native element type.");

When it happens

Trigger: Declaring a property whose element type needs conversion (e.g. List<Guid>, List<DateTimeOffset>, List<SomeEnum>, or a custom value type) where EF Core installs a value converter on the element mapping.

Common situations: Storing collections of types that are not natively JSON-serializable by Cosmos (enums stored as int, DateOnly, strongly-typed IDs); applying HasConversion on an element; upgrading EF Core where the element-mapping pipeline now propagates converters more aggressively.

Related errors

• A full-text index is defined for
• A full-text index on
• A partition key is defined on entity type
• A vector index is defined for
• A vector index on ' ' is defined over properties ` `. A…

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

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