dotnet/efcore · error · InvalidOperationException

Navigation from JSON-mapped entity '{jsonEntity}' to its par

Error message

Navigation from JSON-mapped entity '{jsonEntity}' to its parent entity '{parentEntity}' using navigation '{navigation}' is not supported. Entities mapped to JSON can only navigate to their children.

What it means

Thrown by JsonQueryExpression.BindStructuralProperty when attempting to traverse a dependent-to-principal navigation (a navigation back to the parent entity) from an entity mapped to JSON. EF Core only supports navigating from parent to children in JSON mappings, not upward from JSON entities to their parents (tracked as issue #28645).

Source

Thrown at src/EFCore.Relational/Query/JsonQueryExpression.cs:171

    /// <param name="structuralProperty">The navigation or complex property to bind.</param>
    /// <returns>An JSON query expression for the target entity or complex type.</returns>
    public virtual JsonQueryExpression BindStructuralProperty(IPropertyBase structuralProperty)
    {
        switch (structuralProperty)
        {
            case INavigation navigation:
            {
                if (StructuralType is not IEntityType entityType)
                {
                    throw new UnreachableException("Navigation on complex JSON type");
                }

                Check.DebugAssert(KeyPropertyMap is not null);

                if (navigation.ForeignKey.DependentToPrincipal == navigation)
                {
                    // issue #28645
                    throw new InvalidOperationException(
                        RelationalStrings.JsonCantNavigateToParentEntity(
                            navigation.ForeignKey.DeclaringEntityType.DisplayName(),
                            navigation.ForeignKey.PrincipalEntityType.DisplayName(),
                            navigation.Name));
                }

                var targetEntityType = navigation.TargetEntityType;
                var newPath = Path.ToList();
                newPath.Add(new PathSegment(GetJsonElement(navigation).PropertyName!));

                var newKeyPropertyMap = new Dictionary<IProperty, ColumnExpression>();
                var targetPrimaryKeyProperties = targetEntityType.FindPrimaryKey()!.Properties.Take(KeyPropertyMap.Count);
                var sourcePrimaryKeyProperties = entityType.FindPrimaryKey()!.Properties.Take(KeyPropertyMap.Count);
                foreach (var (target, source) in targetPrimaryKeyProperties.Zip(sourcePrimaryKeyProperties, (t, s) => (t, s)))
                {
                    newKeyPropertyMap[target] = KeyPropertyMap[source];
                }

View on GitHub (pinned to 3a2006ef56)

Solutions

Rewrite the query to traverse from parent to child instead of child to parent: filter on the parent entity directly.
Move the navigation out of JSON mapping (use a regular FK relationship instead of ToJson) if bidirectional navigation is needed.
If you need to query the JSON entity independently, project the parent's key into the JSON document as a scalar and query by that.
Track the issue (#28645) for future EF Core support of upward JSON navigation.

Example fix

// before — navigating from JSON child back to parent
var query = context.Customers
    .SelectMany(c => c.Addresses) // Addresses is ToJson-mapped
    .Where(a => a.Customer.Name == "Acme"); // Customer is parent nav → throws

// after — query from parent instead
var query = context.Customers
    .Where(c => c.Name == "Acme")
    .SelectMany(c => c.Addresses);

Defensive patterns

Strategy: try-catch

Try / catch

try
{
    var result = await context.Customers
        .SelectMany(c => c.Addresses)
        .Where(a => a.Customer.Name == "Acme")
        .ToListAsync();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("not supported") && ex.Message.Contains("JSON"))
{
    // Rewrite: query from parent instead of from JSON child
    var result = await context.Customers
        .Where(c => c.Name == "Acme")
        .SelectMany(c => c.Addresses)
        .ToListAsync();
}

Prevention

Always traverse JSON relationships from parent to child, never child to parent.
Review all LINQ queries that touch JSON-mapped owned types for reverse navigation patterns.
Document which navigations are JSON-mapped so developers know to avoid upward traversal.
Consider using regular FK relationships (not ToJson) if bidirectional navigation is required.

When it happens

Trigger: A LINQ query navigates from a JSON-mapped owned entity back to its parent: e.g., context.Customers.SelectMany(c => c.Addresses).Where(a => a.Customer.Name == ...) where Addresses is JSON-mapped and Customer is the parent navigation. The navigation.ForeignKey.DependentToPrincipal check catches this reverse traversal.

Common situations: Querying JSON-mapped owned collections and filtering/projecting through the parent navigation. Using a JSON-mapped entity in a join or subquery that requires resolving the parent reference. Moving a navigation that was previously table-based into JSON mapping without adjusting queries.

Related errors

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