dotnet/efcore · error · InvalidOperationException

The LINQ expression '{expression}' could not be translated.

Error message

The LINQ expression '{expression}' could not be translated. Either rewrite the query in a form that can be translated, or switch to client evaluation explicitly by inserting a call to 'AsEnumerable', 'AsAsyncEnumerable', 'ToList', or 'ToListAsync'. See https://go.microsoft.com/fwlink/?linkid=2101038 for more information.

What it means

Thrown by CosmosProjectionBindingExpressionVisitor during client-evaluation when it encounters a ParameterExpression that the SQL translator cannot turn into a Cosmos SQL expression. ParameterExpression here means an unbound lambda parameter that the provider could not push down or rewrite; the inner SQL translator already failed and the visitor cannot recover, so it surfaces the generic TranslationFailed message with the offending expression printed.

Source

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

            case NewExpression or MemberInitExpression or StructuralTypeShaperExpression or IncludeExpression:
                return base.Visit(expression);

            case not null when _clientEval:
            {
                switch (expression)
                {
                    case ConstantExpression:
                        return expression;

                    case QueryParameterExpression queryParameter:
                        return Expression.Call(
                            GetParameterValueMethodInfo.MakeGenericMethod(queryParameter.Type),
                            QueryCompilationContext.QueryContextParameter,
                            Expression.Constant(queryParameter.Name));

                    case ParameterExpression parameterExpression:
                        throw new InvalidOperationException(CoreStrings.TranslationFailed(parameterExpression.Print()));

                    case MaterializeCollectionNavigationExpression:
                        return base.Visit(expression);
                }

                switch (_sqlTranslator.TranslateProjection(expression))
                {
                    case SqlExpression sqlExpression:
                        return new ProjectionBindingExpression(
                            _selectExpression, _selectExpression.AddToProjection(sqlExpression), expression.Type.MakeNullable());

                    case StructuralTypeShaperExpression shaper:
                        return base.Visit(shaper);
                }

                if (expression is MethodCallExpression
                    {
                        Method: { IsGenericMethod: true } method,

View on GitHub (pinned to dbf9771522)

Solutions

1. Simplify the projection to only translatable operators; move the non-translatable logic after a client-side boundary such as AsEnumerable().
2. Replace parameter references with constants where the value is fixed, or pass them via FromSqlRaw parameters if supported.
3. Restructure the query so the part referencing the parameter is evaluated client-side after AsEnumerable, not in the server projection.

Example fix

// before
var prefix = GetPrefix();
var results = await db.Items
    .Select(i => Format(i.Name, prefix)) // Format is not translatable
    .ToListAsync();

// after
var results = (await db.Items.Select(i => i.Name).ToListAsync())
    .Select(name => Format(name, prefix));

try
{
    return await query.ToListAsync();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("could not be translated"))
{
    // Fall back: materialize server-side, finish shaping client-side
    return (await query.AsQueryable().Select(x => /* only scalars */).ToListAsync());
}

When it happens

Trigger: A LINQ query whose projection references a captured/parameter variable in a way Cosmos cannot translate, e.g. projecting ctx.Set<T>().Where(x => x.Id == someLocalVar) and then composing a non-translatable selector over it, forcing partial client eval that hits a raw parameter.

Common situations: Using unsupported LINQ operators in the Select clause, or referencing external queryables/parameters inside the projection that the Cosmos translator does not understand. Combining ToArray on a subquery composed with operators the provider cannot push down.

Related errors

• The '{methodName}' method is not supported because the query
• The LINQ expression '{expression}' could not be translated.
• The LINQ expression '{expression}' could not be translated.
• The LINQ expression '{expression}' could not be translated.
• The LINQ expression '{expression}' could not be translated.

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