dotnet/efcore · error · NotSupportedException

Unhandled expression node type '{nodeType}'.

Error message

Unhandled expression node type '{nodeType}'.

What it means

Thrown when the shaped query's underlying QueryExpression is not a SelectExpression. The Cosmos shaper compiler only knows how to compile a Cosmos SelectExpression; any other expression type as the query root is an unexpected, unsupported state that triggers NotSupportedException.

Source

Thrown at src/EFCore.Cosmos/Query/Internal/CosmosShapedQueryCompilingExpressionVisitor.cs:62

        var (paging, maxItemCount, continuationToken, responseContinuationTokenLimitInKb) =
            (false, (SqlParameterExpression)null, (SqlParameterExpression)null, (SqlParameterExpression)null);

        // If the query is terminated ToPageAsync(), CosmosQueryableMethodTranslatingExpressionVisitor composed a PagingExpression on top
        // of the shaper. We remove that to get the shaper for each actual document being read (as opposed to the page of those documents),
        // and extract the pagination arguments.
        if (shaperBody is PagingExpression pagingExpression)
        {
            paging = true;
            maxItemCount = pagingExpression.MaxItemCount;
            continuationToken = pagingExpression.ContinuationToken;
            responseContinuationTokenLimitInKb = pagingExpression.ResponseContinuationTokenLimitInKb;

            shaperBody = pagingExpression.Expression;
        }

        if (shapedQueryExpression.QueryExpression is not SelectExpression selectExpression)
        {
            throw new NotSupportedException(CoreStrings.UnhandledExpressionNode(shapedQueryExpression.QueryExpression));
        }

        VerifyNoClientConstant(shaperBody);

        // Because the shaper might process the data twice (duplicated shaper),
        // we pass the data as ROM, and the shaper will create a JsonReaderData where needed.
        var dataParameter = Parameter(typeof(ReadOnlyMemory<byte>), "data");
        // The shaper will always read the whole next json token/object, and will know how many bytes that was
        // we get the amount of bytes read from the shaper, so that we can advance the data in the QueryingEnumerable as needed, without having to scan the data twice (once for shaper, once for advancing the data).
        var bytesConsumedParameter = Parameter(typeof(int).MakeByRefType(), "bytesConsumed");
        var shaperLambda = new ShaperProcessingExpressionVisitor(this, selectExpression, dataParameter, bytesConsumedParameter)
            .ProcessShaper(shaperBody);

        var cosmosQueryContextConstant = Convert(QueryCompilationContext.QueryContextParameter, typeof(CosmosQueryContext));
        var shaperConstant = Constant(shaperLambda.Compile());
        var contextTypeConstant = Constant(_contextType);
        var rootEntityTypeConstant = Constant(rootEntityType);
        var threadSafetyConstant = Constant(_threadSafetyChecksEnabled);

View on GitHub (pinned to dbf9771522)

Solutions

1. Simplify the query to rule out an unsupported construct triggering the path.
2. Upgrade to the latest EF Core Cosmos patch; if it persists, report a bug with the query.
3. Avoid mixing providers or internal query APIs with Cosmos queries.
4. Reproduce with the minimal query and file an issue in the EF Core repo.

try
{
    return await query.ToListAsync();
}
catch (NotSupportedException ex) when (ex.Message.Contains("Unhandled expression node"))
{
    logger.LogCritical(ex, "Unsupported query shape; report to EF Core");
    throw;
}

When it happens

Trigger: Internal: the query pipeline produced a non-SelectExpression QueryExpression for a Cosmos query. Externally rare; typically indicates a bug in the provider or an unsupported query construct that bypassed normal SelectExpression construction.

Common situations: Provider version bugs, combining Cosmos with providers incorrectly, or using internal/extensibility APIs that inject non-SelectExpression nodes. After upgrading EF Core with a regression.

Related errors

• The LINQ expression '{expression}' could not be translated.
• The LINQ expression '{expression}' could not be translated.
• Including navigation '{navigation}' is not supported as the
• Unhandled expression '{expression}' of type '{expressionType
• Cosmos SQL does not allow Offset without Limit. Consider spe

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