Error Codes Reference

Every validation failure in DynamicWhere.ex throws a LogicException (which inherits from Exception). The Message property carries one of the 31 stable error strings listed below, so you can pattern‑match them in middleware and surface meaningful problems to API callers.

How errors are raised

Validation runs clause by clause while the query is composed, not in a single pass before it. Most shapes — Filter, ConditionGroup, GroupBy, PageBy — are checked before their part of the query executes, but two entry points reach the database first: ToListDynamic and ToListAsyncDynamic run the COUNT query before validating Orders, Page and Selects. ToListAsync(Segment) combines its sets into one query and validates every clause before that query runs. The async overloads are async methods, so their exceptions surface at the await rather than at the call.

LogicException is the usual type, but not the only one a caller sees. A null argument raises ArgumentNullException; a guarded type raises PolicyException, which derives from LogicException; and input that passes validation but not the expression parser raises ParseException from System.Linq.Dynamic.Core.

app.MapPost("/customers/search", async (Filter filter, AppDbContext db) =>
{
    try
    {
        var result = await db.Customers.ToListAsync(filter);
        return Results.Ok(result);
    }
    catch (LogicException ex)
    {
        // ex.Message is one of the stable error codes below
        return Results.BadRequest(new { error = ex.Message });
    }
});

All 31 error codes

Codes wrapped in (parens) are parameterized — the bracketed token in the message is replaced at runtime with the offending operator, alias, aggregator, type, or field name.

One failure still carries a literal message rather than one of these codes: Unsupported combination of DataType '{type}' and Operator '{op}'. for a pair the predicate builder has no form for. It is the only one left — the Select projection refusal became the code SelectTypeMustHaveParameterlessConstructor in 3.1.0.

LogicException.Subject

LogicException gained a second constructor in 3.1.0 — LogicException(string message, string? subject) — and the matching read-only property Subject (string?). It carries what a refusal is about where the code alone does not say: the rejected type's Name on SelectTypeMustHaveParameterlessConstructor, the field — or the Having alias — on AmbiguousDateFormat and on an InvalidFormat raised by a Date or DateTime value, and the offending first segment, trimmed, on FieldPath[{path}]StartsWithReservedName. Under ApplyPolicy the field is named as the caller wrote it, so a [DwAlias] name is never swapped for the member it hides. It is null for every other code, including InvalidFormat on a Guid, Number or Boolean value; the parameterized codes already interpolate their operator, alias, aggregator, type, or field name into the message themselves.

Keeping the type name out of the message is the point: a code that carried it would be a different string on every type, and neither your middleware nor an error envelope could match on it.

catch (LogicException ex)
{
    // ex.Message   -> "SelectTypeMustHaveParameterlessConstructor"
    // ex.Subject   -> "CustomerRow"
    //
    // ex.Message   -> "AmbiguousDateFormat"
    // ex.Subject   -> "CreatedAt"
    //
    // null for most other codes
    return Results.BadRequest(new { error = ex.Message, subject = ex.Subject });
}

Where each error lives

Each error is raised by a specific validation entry point. Follow the link for the full validation rules and the exact shape that triggers each code:

• Condition validation → InvalidField (also raised for any other blank or unresolvable field path — OrderBy, GroupBy, AggregateBy, Having, Summary.Orders), RequiredValues, NotRequiredValues, RequiredTwoValue, RequiredOneValue(op), InvalidFormat, AmbiguousDateFormat (the two format codes are also raised for a date value in a Having condition), StartsWithReservedName(path) (also raised for any other field path whose first segment is one of the parser's own words — OrderBy, Selects, GroupBy, AggregateBy).
• ConditionGroup validation → ConditionsUniqueSort, SubConditionsGroupsUniqueSort.
• Page validation → InvalidPageNumber, InvalidPageSize.
• GroupBy validation → GroupByMustHaveFields, GroupByFieldsMustBeUnique, GroupByFieldCannotBeComplexType, GroupByFieldCannotBeCollection, and the AggregateBy codes InvalidAlias, AggregationFieldMustBeSimpleType, AggregationFieldCannotBeCollection, AggregationAliasesMustBeUnique, AggregationAliasCannotBeGroupByField(alias), UnsupportedAggregatorForType(agg, type) — all reachable through Group as well as through Summary.
• Summary validation → SummaryOrderFieldMustExistInGroupByOrAggregate(f), HavingFieldMustExistInAggregateByAlias(f), plus every GroupBy code above from the nested GroupBy.
• Segment validation → SetsUniqueSort and RequiredIntersection, plus the ConditionGroup errors of each set and the Selects, OrderBy and Page errors of the segment itself.
• Select / SelectDynamic → MustHaveFields, for an empty Select, SelectDynamic, or Filter.Selects list, and SelectTypeMustHaveParameterlessConstructor, for a typed Select<T> the projection cannot construct.
• Order → OrderFieldCannotEndOnComplexCollection(f), when an order path ends on a collection of entities.

See also

• Breaking Changes & Known Limitations → behaviour that is not an error but may surprise you.
• Filter → the most common entry point that triggers these validations.