dotnet/efcore · error · InvalidOperationException

Including navigation '{navigation}' is not supported as the

Error message

Including navigation '{navigation}' is not supported as the navigation is not embedded in same resource.

What it means

Thrown by CosmosProjectionBindingExpressionVisitor when a MaterializeCollectionNavigationExpression is processed and the navigation is not an embedded collection (Navigation.IsEmbedded() is false). Cosmos EF Core only supports server-side Include for navigations that are stored as embedded JSON arrays inside the same document; a related entity stored in a separate container cannot be joined at query time. The message names the navigation.

Source

Thrown at src/EFCore.Cosmos/Query/Internal/CosmosProjectionBindingExpressionVisitor.cs:335

                    {
                        // This is to handle have correct type for the shaper expression. It is later fixed in MatchTypes.
                        // This mirrors for structural types what we do for scalars.
#pragma warning disable EF1001 // Internal EF Core API usage.
                        structuralTypeShaper = structuralTypeShaper.MakeClrTypeNullable();
#pragma warning restore EF1001 // Internal EF Core API usage.
                    }
                }

                structuralTypeShaper = structuralTypeShaper.Update(projectionBinding);

                return structuralTypeShaper;
            }

            case MaterializeCollectionNavigationExpression materializeCollectionNavigationExpression:
                if (materializeCollectionNavigationExpression.Navigation is not INavigation includableCollectionNavigation
                    || !includableCollectionNavigation.IsEmbedded())
                {
                    throw new InvalidOperationException(
                        CosmosStrings.NonEmbeddedIncludeNotSupported(materializeCollectionNavigationExpression.Navigation));
                }

                var subquery = materializeCollectionNavigationExpression.Subquery;
                if (subquery is MethodCallExpression { Method.IsGenericMethod: true } methodCallSubquery)
                {
                    // strip .Select(x => x) and .AsQueryable()
                    if (methodCallSubquery.Method.GetGenericMethodDefinition() == QueryableMethods.Select
                        && methodCallSubquery.Arguments[0] is MethodCallExpression selectSourceMethod)
                    {
                        methodCallSubquery = selectSourceMethod;
                    }

                    if (methodCallSubquery.Method.IsGenericMethod
                        && methodCallSubquery.Method.GetGenericMethodDefinition() == QueryableMethods.AsQueryable)
                    {
                        subquery = methodCallSubquery.Arguments[0];
                    }

View on GitHub (pinned to dbf9771522)

Solutions

1. Configure the navigation as embedded: own the collection (OwnsMany) so its data lives inside the same Cosmos document, then Include works.
2. If the related data must live in a separate container, issue a separate query by key and stitch results client-side instead of using Include.

Example fix

// before
public class Order {
    public List<OrderItem> Items { get; set; } // separate container
}
var orders = await db.Orders.Include(o => o.Items).ToListAsync();

// after: embed items inside the order document
modelBuilder.Entity<Order>().OwnsMany(o => o.Items);
var orders = await db.Orders.Include(o => o.Items).ToListAsync();

// Assert navigations used with Include are embedded before running queries
foreach (var nav in typeof(MyContext).Assembly.GetTypes()
            .SelectMany(t => t.GetProperties())
            .Where(p => p.PropertyType.IsGenericType && p.PropertyType.GetGenericTypeDefinition() == typeof(List<>)))
{
    // cross-check against modelBuilder: ensure OwnsMany is declared for each included collection
}

static bool IsEmbeddedCollection(INavigation n) => n.IsEmbedded();

When it happens

Trigger: Calling .Include(x => x.RelatedCollection) where RelatedCollection is a navigation not configured as embedded (it maps to a separate Cosmos container or is a pure relationship without embedded storage), inside a query that triggers materialization of that collection.

Common situations: Treating Cosmos like a relational DB and defining one-to-many relationships across separate containers expecting them to join. Including navigations on entities migrated from SQL Server without marking them embedded.

Related errors

• The LINQ expression '{expression}' could not be translated.
• Unhandled expression '{expression}' of type '{expressionType
• Cosmos SQL does not allow Offset without Limit. Consider spe
• JsonCantNavigateToParentEntity
• The type '{givenType}' cannot be mapped as a dictionary beca

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