dotnet/efcore · error · InvalidOperationException

TranslationFailedWithDetails

TranslationFailedWithDetails

Error message

The LINQ expression '{expression}' could not be translated. Additional information: {details} 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

Same translation-failure path as 656, but when TranslationErrorDetails is non-null (line 141-143), CoreStrings.TranslationFailedWithDetails is thrown instead, appending the accumulated detailed sub-error messages. The details often pinpoint which nested expression first failed to translate, making diagnosis easier than the bare TranslationFailed.

Source

Thrown at src/EFCore.Relational/Query/RelationalQueryableMethodTranslatingExpressionVisitor.cs:140

                    {
                        string call;
                        var methodInfo = function.DbFunctions.Last().MethodInfo;
                        if (methodInfo != null)
                        {
                            var methodCall = Expression.Call(
                                // Declaring types would be derived db context.
                                Expression.Default(methodInfo.DeclaringType!),
                                methodInfo,
                                tableValuedFunctionQueryRootExpression.Arguments);

                            call = methodCall.Print();
                        }
                        else
                        {
                            call = $"{function.DbFunctions.Last().Name}()";
                        }

                        throw new InvalidOperationException(
                            TranslationErrorDetails == null
                                ? CoreStrings.TranslationFailed(call)
                                : CoreStrings.TranslationFailedWithDetails(call, TranslationErrorDetails));
                    }

                    arguments.Add(sqlArgument);
                }

                var entityType = tableValuedFunctionQueryRootExpression.EntityType;
                var alias = _sqlAliasManager.GenerateTableAlias(function);
                var translation = new TableValuedFunctionExpression(alias, function, arguments);
                var queryExpression = CreateSelect(entityType, translation);

                return CreateShapedQueryExpression(entityType, queryExpression);
            }

            case EntityQueryRootExpression entityQueryRootExpression
                when entityQueryRootExpression.GetType() == typeof(EntityQueryRootExpression)

View on GitHub (pinned to dbf9771522)

Solutions

Read the 'Additional information' details to find the specific inner expression that failed, then target that fragment.
Rewrite the failing fragment to a translatable form (parameters, supported methods, EF.Functions).
Force client evaluation only for the untranslatable sub-expression by splitting the query with AsEnumerable/ToList at the right boundary.
Simplify nested subqueries; materialize intermediate results if needed.

Example fix

// before (nested subquery fails translation; details point to inner method)
var q = db.Orders.Select(o => new {
    o.Id,
    First = o.Items.OrderBy(i => i.Price).Select(i => Helper.Fmt(i.Sku)).FirstOrDefault()
});

// after (move untranslatable formatting client-side after projection)
var raw = db.Orders.Select(o => new {
    o.Id,
    FirstSku = o.Items.OrderBy(i => i.Price).Select(i => i.Sku).FirstOrDefault()
}).AsEnumerable();
var q = raw.Select(o => new { o.Id, First = Helper.Fmt(o.FirstSku) });

Defensive patterns

Strategy: try-catch

Try / catch

try { var r = await query.ToListAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("could not be translated"))
{
    // The 'Additional information' section names the inner failing expression;
    // target that fragment, rewrite or split with AsEnumerable at the boundary.
}

Prevention

Read the 'Additional information' details to find the first failing inner expression.
Flatten deeply nested subqueries; materialize intermediate results when needed.
Place AsEnumerable/ToList at the exact boundary where client evaluation is acceptable.
Test complex queries in isolation to surface detailed errors early.

When it happens

Trigger: A complex LINQ query where translation fails and the translator collected one or more detailed error strings (e.g. from nested subquery translation, TVF arguments, or group-by element translation). The wrapped details identify the inner untranslatable expressions.

Common situations: Deeply nested queries, subqueries inside Select, TVF calls with multiple failing arguments, composite expressions where the first failure triggers detail collection; upgrading EF Core where stricter translation surfaces previously-implicit client evaluation.

Related errors

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