dotnet/efcore · error · InvalidOperationException

Ordering using a scoring function is mutually exclusive…

Error message

Ordering using a scoring function is mutually exclusive with other forms of ordering.

What it means

AppendOrdering in Cosmos SelectExpression throws OrderByScoringFunctionMixedWithRegularOrderby when exactly one of the existing and appended orderings is a scoring function. Cosmos treats scoring-function ordering as mutually exclusive with regular property ordering; you cannot ThenBy a property on top of a VectorDistance/FullTextScore ordering or vice-versa.

Solutions

Remove the non-scoring ThenBy/OrderBy clause.
Apply the secondary property ordering client-side after materializing the ranked page.

Example fix

// before
var q = db.Items
    .OrderBy(i => EF.Functions.VectorDistance(i.Embedding, v))
    .ThenBy(i => i.Name);

// after - drop the tiebreaker from the SQL query
var q = db.Items
    .OrderBy(i => EF.Functions.VectorDistance(i.Embedding, v));

Defensive patterns

Strategy: validation

Validate before calling

// Reject mixing scoring and non-scoring orderings.
bool hasScoring = orderings.Any(o => IsScoringExpression(o.Expression));
bool hasRegular = orderings.Any(o => !IsScoringExpression(o.Expression));
if (hasScoring && hasRegular) throw new InvalidOperationException("Do not mix scoring and property orderings.");

Prevention

When using a scoring-function ordering, do not add property ThenBy clauses.
Apply tiebreakers client-side after materializing the page.
Encapsulate ranking query construction in a helper that prevents mixed orderings.

When it happens

Trigger: .OrderBy(EF.Functions.VectorDistance(...)).ThenBy(x => x.Name) or .OrderBy(x => x.Name).ThenBy(EF.Functions.VectorDistance(...)).

Common situations: Adding a deterministic tiebreaker property (Name, Date, Id) alongside a scoring-function ordering.

Related errors

AI-assisted analysis of dotnet/efcore@3a2006ef56 (2026-08-11). Data as JSON: /api/errors/c0900f935354a1b5. Report an issue: GitHub.

Appendix: source

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

        _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 } }];
            var appendingScoringFunctionOrdering = orderingExpression.Expression is SqlFunctionExpression { IsScoringFunction: true };
            if (appendingScoringFunctionOrdering || existingScoringFunctionOrdering)
            {
                throw new InvalidOperationException(
                    appendingScoringFunctionOrdering && existingScoringFunctionOrdering
                        ? CosmosStrings.OrderByMultipleScoringFunctionWithoutRrf(nameof(CosmosDbFunctionsExtensions.Rrf))
                        : CosmosStrings.OrderByScoringFunctionMixedWithRegularOrderby);
            }
        }

        if (_orderings.FirstOrDefault(o => o.Expression.Equals(orderingExpression.Expression)) == null)
        {
            _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>

View on GitHub (pinned to 3a2006ef56)