dotnet/efcore · error · InvalidOperationException

The table '{table}' cannot be used for entity type '{entityT

Error message

The table '{table}' cannot be used for entity type '{entityType}' since it is being used for entity type '{otherEntityType}' and the comment '{comment}' does not match the comment '{otherComment}'.

What it means

Table-level comments (`.HasComment` on the entity/table, not column comments) must be consistent across all entity types sharing a table, because there is only one table object to carry the comment. The validator at line 1231-1244 compares comments between connected types during the BFS and throws if both are non-null and differ.

Source

Thrown at src/EFCore.Relational/Infrastructure/RelationalModelValidator.cs:1237

                        throw new InvalidOperationException(
                            RelationalStrings.IncompatibleTableKeyNameMismatch(
                                table.DisplayName(),
                                entityType.DisplayName(),
                                nextEntityType.DisplayName(),
                                key.GetName(table),
                                key.Properties.Format(),
                                otherKey.GetName(table),
                                otherKey.Properties.Format()));
                    }
                }

                var nextComment = nextEntityType.GetComment();
                if (comment != null)
                {
                    if (nextComment != null
                        && !comment.Equals(nextComment, StringComparison.Ordinal))
                    {
                        throw new InvalidOperationException(
                            RelationalStrings.IncompatibleTableCommentMismatch(
                                table.DisplayName(),
                                entityType.DisplayName(),
                                nextEntityType.DisplayName(),
                                comment,
                                nextComment));
                    }
                }
                else
                {
                    comment = nextComment;
                }

                if (isExcluded.Equals(!nextEntityType.IsTableExcludedFromMigrations(table)))
                {
                    throw new InvalidOperationException(
                        RelationalStrings.IncompatibleTableExcludedMismatch(
                            table.DisplayName(),

View on GitHub (pinned to dbf9771522)

Solutions

Set the table comment on only one of the sharing entity types (the principal) and remove the others.
If comments are set on multiple types, make the string identical across all of them.
Use column-level comments (.Property(...).HasComment(...)) instead if different aspects need describing.

Example fix

// before
modelBuilder.Entity<Order>()
    .ToTable("Orders", t => t.HasComment("Customer orders"));
modelBuilder.Entity<OrderDetail>()
    .ToTable("Orders", t => t.HasComment("Order line items"));

// after - single source of truth for the table comment
modelBuilder.Entity<Order>()
    .ToTable("Orders", t => t.HasComment("Customer orders"));
modelBuilder.Entity<OrderDetail>()
    .ToTable("Orders");

Defensive patterns

Strategy: validation

Validate before calling

var byTable = modelBuilder.Model.GetEntityTypes()
    .Where(e => !e.IsMappedToJson())
    .GroupBy(e => (e.GetTableName(), e.GetSchema()))
    .Where(g => g.Count() > 1);
foreach (var grp in byTable)
{
    var comments = grp.Select(e => e.GetComment()).Where(c => c != null).Distinct().ToList();
    if (comments.Count > 1)
        throw new InvalidOperationException(
            $"Shared table '{grp.Key.Item1}' has mismatched comments: {string.Join(" | ", comments)}");
}

Prevention

Set the table comment (.ToTable(name, t => t.HasComment(...))) on exactly one type per shared table.
Use column comments (.Property(...).HasComment(...)) for per-property documentation.
Centralize table-comment configuration in a single helper to avoid divergent strings.

When it happens

Trigger: Calling `.ToTable("T", t => t.HasComment("..."))` (or `.HasComment` via table builder) with different comment strings on two entity types mapped to the same table. Detected when both `comment` and `nextComment` are non-null and unequal.

Common situations: One team annotates the table via the principal entity, another via the owned/dependent entity with a different description; copy-paste of entity config leaving a stale comment; merging two models.

Related errors

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