dotnet/efcore · error · InvalidOperationException

An Azure Cosmos DB container name is defined on entity type

Error message

An Azure Cosmos DB container name is defined on entity type '{entityType}', which inherits from '{baseEntityType}'. Container names must be defined on the root entity type of a hierarchy.

What it means

In a TPH hierarchy that shares one Cosmos container, the container name may only be set on the root entity type. CosmosModelValidator throws InvalidOperationException via CosmosStrings.ContainerNotOnRoot when a derived entity type that has a BaseType also carries a container-name annotation, because all documents in a hierarchy must live in the root's container.

Source

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

    /// </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))
        {
            var container = entityType.GetContainer();
            if (container == null)
            {
                continue;
            }

            if (entityType.BaseType != null
                && entityType.FindAnnotation(CosmosAnnotationNames.ContainerName)?.Value != null)
            {
                throw new InvalidOperationException(
                    CosmosStrings.ContainerNotOnRoot(entityType.DisplayName(), entityType.BaseType.DisplayName()));
            }

            var ownership = entityType.FindOwnership();
            if (ownership != null)
            {
                throw new InvalidOperationException(
                    CosmosStrings.OwnedTypeDifferentContainer(
                        entityType.DisplayName(),
                        ownership.PrincipalEntityType.DisplayName(),
                        container));
            }

            if (entityType.GetContainingPropertyName() != null)
            {
                throw new InvalidOperationException(
                    CosmosStrings.ContainerContainingPropertyConflict(
                        entityType.DisplayName(),

View on GitHub (pinned to dbf9771522)

Solutions

1. Set the container name only on the base/root entity type and remove the ToContainer call from derived types.
2. If types truly need separate containers, they should not be in the same inheritance hierarchy (break the hierarchy).

Example fix

// before (container set on derived type)
modelBuilder.Entity<Animal>().ToContainer("animals");
modelBuilder.Entity<Cat>().ToContainer("cats"); // Cat derives from Animal

// after (container only on the root)
modelBuilder.Entity<Animal>().ToContainer("animals");
// Cat inherits the container from Animal

// Ensure ToContainer is only set on hierarchy roots.
foreach (var et in modelBuilder.Model.GetEntityTypes())
{
    if (et.BaseType != null
        && et.FindAnnotation(CosmosAnnotationNames.ContainerName)?.Value != null)
    {
        throw new InvalidOperationException($"Remove ToContainer from derived type {et.Name}.");
    }
}

static bool IsHierarchyRoot(IEntityType et) => et.BaseType is null;

try { context.Database.EnsureCreated(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("root entity type"))
{ throw new InvalidOperationException("Set container names only on the base/root entity type.", ex); }

When it happens

Trigger: Calling ToContainer/HasContainerName on a derived entity type that participates in an inheritance hierarchy (has a BaseType).

Common situations: Applying a per-type container convention that fires for derived types; copy-pasting ToContainer across an inheritance chain; migrating from a per-type mapping scheme.

Related errors

• The entity type '{entityType}' is owned by the entity type '
• The entity type '{entityType}' is mapped to the container '{
• The entity type '{entityType}' is sharing the container '{co
• Cosmos automatic-indexing configuration was set on entity ty
• A partition key is defined on entity type '{entityType}', wh

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