dotnet/efcore · error · InvalidOperationException

Ordering based on scoring function is not supported inside '

Error message

Ordering based on scoring function is not supported inside '{orderByDescending}'. Use '{orderBy}' instead.

What it means

Cosmos Full Text Search scoring functions (e.g. FullTextScore / RRF) rank by relevance, where a higher score means a better match, so they can only appear in ascending OrderBy. ApplyOrdering throws InvalidOperationException when the ordering expression is a scoring function but IsAscending is false. Use OrderBy (ascending) instead of OrderByDescending.

Source

Thrown at src/EFCore.Cosmos/Query/Internal/Expressions/SelectExpression.cs:462

    ///     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 void ApplyOffset(SqlExpression sqlExpression)
        => Offset = sqlExpression;

    /// <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 void ApplyOrdering(OrderingExpression orderingExpression)
    {
        if (orderingExpression is { Expression: SqlFunctionExpression { IsScoringFunction: true }, IsAscending: false })
        {
            throw new InvalidOperationException(
                CosmosStrings.OrderByDescendingScoringFunction(nameof(Queryable.OrderByDescending), nameof(Queryable.OrderBy)));
        }

        _orderings.Clear();
        _orderings.Add(orderingExpression);
    }

    /// <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 void AppendOrdering(OrderingExpression orderingExpression)
    {
        if (_orderings.Count > 0)
        {
            var existingScoringFunctionOrdering = _orderings is [{ Expression: SqlFunctionExpression { IsScoringFunction: true } }];

View on GitHub (pinned to dbf9771522)

Solutions

Replace OrderByDescending(scoringFunction) with OrderBy(scoringFunction) — relevance is already most-relevant-first.
If you need least-relevant first, materialize the results and reverse client-side.
Double-check that the function you call is the scoring variant; non-scoring functions are ordered normally.

Example fix

// before
var q = ctx.Articles
    .OrderByDescending(a => EF.Functions.FullTextScore(a.Body, "term"));

// after
var q = ctx.Articles
    .OrderBy(a => EF.Functions.FullTextScore(a.Body, "term"));

Defensive patterns

Strategy: validation

Validate before calling

// Static helper: scoring functions must be ordered ascending.
static IQueryable<T> OrderByScoring<T>(IQueryable<T> q, Expression<Func<T, double>> score)
    => q.OrderBy(score); // never OrderByDescending

Try / catch

try { var q = ctx.Articles.OrderByDescending(a => Scoring(a)).ToList(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("scoring function"))
{ /* switch to OrderBy */ }

Prevention

Always order scoring functions ascending.
Wrap full-text scoring ordering in a helper that forbids descending.

When it happens

Trigger: Writing `query.OrderByDescending(x => EF.Functions.FullTextScore(...))` or any descending ordering whose expression is a scoring (IsScoringFunction) SqlFunctionExpression.

Common situations: Assuming descending relevance is allowed; copy-pasting a relational ORDER BY pattern into a Cosmos full-text query.

Related errors

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