dotnet/efcore · error · InvalidOperationException

Unable to bind '{memberType}' '{member}' to an entity projec

Error message

Unable to bind '{memberType}' '{member}' to an entity projection of {entityType}.

What it means

StructuralTypeProjectionExpression.BindProperty throws InvalidOperationException when the given IProperty is not declared on (or assignable to/from) the structural type being projected. The provider cannot read a JSON field for a property that does not belong to the projected entity/structural type.

Source

Thrown at src/EFCore.Cosmos/Query/Internal/Expressions/StructuralTypeProjectionExpression.cs:107

    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
    /// </summary>
    public virtual Expression Update(Expression @object)
        => ReferenceEquals(@object, Object)
            ? this
            : new StructuralTypeProjectionExpression(@object, StructuralType);

    /// <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>
    public virtual Expression BindProperty(IProperty property, bool clientEval)
    {
        if (!StructuralType.IsAssignableFrom(property.DeclaringType)
            && !property.DeclaringType.IsAssignableFrom(StructuralType))
        {
            throw new InvalidOperationException(
                CosmosStrings.UnableToBindMemberToEntityProjection("property", property.Name, StructuralType.DisplayName()));
        }

        if (!_propertyExpressionsMap.TryGetValue(property, out var expression))
        {
            expression = new ScalarAccessExpression(
                Object, property.GetJsonPropertyName(), property.ClrType, property.GetTypeMapping());
            _propertyExpressionsMap[property] = expression;
        }

        if (!clientEval
            // TODO: We shouldn't be returning null from here. See issues #17670 and #14121.
            && expression.PropertyName?.Length is null or 0)
        {
            // Non-persisted property can't be translated
            return null!;
        }

View on GitHub (pinned to dbf9771522)

Solutions

1. Navigate through the correct path (e.g. bind Customer.Name via the Customer navigation, not as Order's own property).
2. Verify the entity/structural type in the projection contains the property; for inheritance, ensure the property is mapped on the correct hierarchy node.
3. In custom translators, pass the IProperty resolved from the structural type you are binding against.

Example fix

// before: binding the wrong property to the wrong projection
projection.BindProperty(customerNameProperty, clientEval: false);

// after: bind via the correct structural type's property
var customerProjection = orderProjection.BindNavigation(customerNav, false);
customerProjection.BindProperty(customerNameProperty, clientEval: false);

// Verify the property belongs to the projected structural type before binding.
static bool IsBindable(ITypeBase structuralType, IProperty p)
    => structuralType.IsAssignableFrom(p.DeclaringType)
       || p.DeclaringType.IsAssignableFrom(structuralType);

static bool PropertyBelongsToProjection(ITypeBase projectionType, IProperty p)
    => projectionType.IsAssignableFrom(p.DeclaringType)
       || p.DeclaringType.IsAssignableFrom(projectionType);

try { var q = query.ToList(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Unable to bind") && ex.Message.Contains("property"))
{ /* navigate to the correct structural type that owns the property */ }

When it happens

Trigger: Binding a property belonging to an unrelated entity against the current projection — e.g. the translator tries to read Order.Customer.Name as a property of Order directly, or a custom translator binds the wrong IProperty.

Common situations: Misconfigured inheritance hierarchies (TPH) where a property is on a sibling type; custom translators passing the wrong IProperty; querying a property via a projection of a different structural type.

Related errors

• Both properties '{property1}' and '{property2}' on entity ty
• The query uses 'NoTrackingWithIdentityResolution' and projec
• The LINQ expression '{expression}' could not be translated.
• The LINQ expression '{expression}' could not be translated.
• Complex projections in subqueries are currently unsupported.

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