dotnet/efcore · error · InvalidOperationException

The property '{property}' on type '{type}' cannot be configu

Error message

The property '{property}' on type '{type}' cannot be configured as not auto-loaded. The Cosmos provider doesn't support partial property loading.

What it means

Cosmos returns whole documents; it cannot perform partial or on-demand property loading. CosmosModelValidator.ValidateAutoLoaded throws InvalidOperationException via CosmosStrings.AutoLoadedCosmosProperty when a property that must be auto-loaded is configured as not auto-loaded, because that implies deferred loading Cosmos does not support.

Source

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

        ValidateDiscriminatorMappings(entityType, logger);
    }

    /// <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 override void ValidateAutoLoaded(
        IProperty property,
        ITypeBase structuralType,
        IDiagnosticsLogger<DbLoggerCategory.Model.Validation> logger)
    {
        base.ValidateAutoLoaded(property, structuralType, logger);

        if (!property.IsAutoLoaded)
        {
            throw new InvalidOperationException(
                CosmosStrings.AutoLoadedCosmosProperty(property.Name, structuralType.DisplayName()));
        }
    }

    /// <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 ValidateSharedContainerCompatibility(
        IModel model,
        IDiagnosticsLogger<DbLoggerCategory.Model.Validation> logger)
    {
        // All entity types mapped to a single container must have the same container-level settings, most notably partition keys.
        var containers = new Dictionary<string, List<IEntityType>>();
        foreach (var entityType in model.GetEntityTypes().Where(et => et.FindPrimaryKey() != null))
        {

View on GitHub (pinned to dbf9771522)

Solutions

Remove the not-auto-loaded / deferred-load configuration so all properties are eagerly (auto) loaded with the document.
Do not use lazy-loading proxies or ILazyLoader with the Cosmos provider.
If you need subsets of data, project to a DTO (Select) instead of relying on partial entity loading.

Example fix

// before (lazy/deferred loading configured for Cosmos)
modelBuilder.Entity<Order>(b =>
{
    b.Navigation(o => o.Details).AutoLoad(false); // not supported on Cosmos
});

// after (auto-load all; project subsets instead)
modelBuilder.Entity<Order>(b =>
{
    b.Navigation(o => o.Details); // loaded with the document
});
// for partial reads, project:
var headers = context.Orders.Select(o => new OrderHeader { Id = o.Id, Total = o.Total });

Defensive patterns

Strategy: validation

Validate before calling

// Do not configure non-auto-loaded on Cosmos entities; assert auto-load where relevant.
foreach (var nav in typeof(Order).GetProperties()
            .Where(p => p.PropertyType.IsClass && p.PropertyType != typeof(string)))
{
    // Simply omit AutoLoad(false); Cosmos loads the whole document.
}

Try / catch

try { context.Database.EnsureCreated(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("not auto-loaded"))
{ throw new InvalidOperationException("Remove deferred/lazy-load config; Cosmos loads whole documents.", ex); }

Prevention

Do not use lazy-loading proxies or ILazyLoader with the Cosmos provider.
Never set IsAutoLoaded(false) on Cosmos entities.
Use Select projections for partial reads instead of deferred property loading.

When it happens

Trigger: Configuring a navigation/property on a Cosmos-mapped entity with non-auto-loaded (deferred) semantics; enabling lazy-loading proxies and expecting per-property loading; explicitly setting a property to load on demand.

Common situations: Migrating a relational model that used lazy loading to Cosmos; combining ILazyLoader with the Cosmos provider; setting IsAutoLoaded(false) on a navigation.

Related errors

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