dotnet/efcore · error · InvalidOperationException

Unhandled expression '{expression}' of type '{expressionType

Error message

Unhandled expression '{expression}' of type '{expressionType}' encountered in '{visitor}'.

What it means

Thrown by CosmosQuerySqlGenerator when its expression switch hits the default arm: the expression node type is not one of the recognized SQL node kinds (ObjectReferenceExpression, OrderingExpression, ProjectionExpression, ScalarAccess/Array/Reference/Subquery, SelectExpression, SourceExpression, SqlBinary/Conditional/Constant/Function/Parameter/Unary, StructuralTypeProjectionExpression). This indicates an internally-malformed query tree reached the SQL emitter and is almost always an EF Core infrastructure bug rather than a user LINQ mistake.

Source

Thrown at src/EFCore.Cosmos/Query/Internal/CosmosQuerySqlGenerator.cs:97

            ObjectFunctionExpression e => VisitObjectFunction(e),
            ObjectReferenceExpression e => VisitObjectReference(e),
            OrderingExpression e => VisitOrdering(e),
            ProjectionExpression e => VisitProjection(e),
            ScalarAccessExpression e => VisitScalarAccess(e),
            ScalarArrayExpression e => VisitScalarArray(e),
            ScalarReferenceExpression e => VisitValueReference(e),
            ScalarSubqueryExpression e => VisitScalarSubquery(e),
            SelectExpression e => VisitSelect(e),
            SourceExpression e => VisitSource(e),
            SqlBinaryExpression e => VisitSqlBinary(e),
            SqlConditionalExpression e => VisitSqlConditional(e),
            SqlConstantExpression e => VisitSqlConstant(e),
            SqlFunctionExpression e => VisitSqlFunction(e),
            SqlParameterExpression e => VisitSqlParameter(e),
            SqlUnaryExpression e => VisitSqlUnary(e),
            StructuralTypeProjectionExpression e => VisitStructuralTypeProjection(e),

            _ => throw new InvalidOperationException(
                CosmosStrings.UnhandledExpressionInVisitor(expression, expression.GetType(), nameof(CosmosQuerySqlGenerator))),
        };

    /// <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>
    protected virtual Expression VisitStructuralTypeProjection(StructuralTypeProjectionExpression structuralTypeProjectionExpression)
    {
        Visit(structuralTypeProjectionExpression.Object);

        return structuralTypeProjectionExpression;
    }

    /// <summary>
    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to

View on GitHub (pinned to dbf9771522)

Solutions

1. Simplify the query to isolate which operator introduces the unsupported node, then evaluate that part client-side.
2. Update the Microsoft.EntityFrameworkCore.Cosmos package to exactly match the EF Core runtime version in use.
3. If the query is minimal and still throws, capture the expressionType from the message and file an EF Core issue; it is a provider gap.

Example fix

// before
var q = db.Items
    .Where(i => SomeUnsupportedOperator(i.Data))
    .ToList();

// after
var all = await db.Items.ToListAsync();
var q = all.Where(i => SomeUnsupportedOperator(i.Data)).ToList();

try
{
    return await query.ToListAsync();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Unhandled expression"))
{
    // Capture expressionType from the message, simplify the query, or materialize client-side
    var all = await db.Set<TEntity>().ToListAsync();
    return /* client-side filter/transformation */;
}

When it happens

Trigger: An expression of a type not in the generator's switch arms reaches Visit; typically produced by another visitor producing a non-Cosmos SqlExpression node. Can be triggered by certain unsupported query shapes that the translator partially handled then passed an unknown node downstream.

Common situations: Provider version mismatch (mixing EF Core runtime version with an older Cosmos provider). Edge-case queries (specific operators, JSON helpers) where the translator emits a node the generator cannot render. Usually not reproducible by simple LINQ.

Related errors

• Cosmos SQL does not allow Offset without Limit. Consider spe
• UnhandledExpressionInVisitor
• Cosmos-specific methods can only be used when the context is
• The LINQ expression '{expression}' could not be translated.
• Including navigation '{navigation}' is not supported as the

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