skip to content

In FluentValidation 12, what do Cascade(CascadeMode.Stop), RuleLevelCascadeMode and ClassLevelCascadeMode each stop, and what replaced StopOnFirstFailure?

level: seniorimportance: should knowfreq 45%

answer

  1. inside a rule versus between rules
  2. the default keeps going
  3. per rule, per class, global
  4. a removed third enum value

basics

~20 s

Both levels default to Continue. Rule level, set by Cascade(CascadeMode.Stop) or RuleLevelCascadeMode, skips a chain's later validators after one fails. Class level, ClassLevelCascadeMode, ends the run after the first failing rule. FluentValidation 12 removed StopOnFirstFailure.

solid answer

~40 s

FluentValidation has two independent cascade levels, both `Continue` by default. **Rule level** works inside one `RuleFor` chain: with `CascadeMode.Stop`, once a validator fails the rest of that chain is skipped. I set it per rule with `.Cascade(CascadeMode.Stop)` right after `RuleFor`, per class with `RuleLevelCascadeMode`, or globally with `ValidatorOptions.Global.DefaultRuleLevelCascadeMode`. **Class level** works between rules: `ClassLevelCascadeMode = CascadeMode.Stop` ends validation after the first rule that added any failure, and that rule may have added more than one unless rule level is also `Stop`. FluentValidation 12 removed `CascadeMode.StopOnFirstFailure` and the old `CascadeMode` properties; the old behaviour maps to rule level `Stop` with class level `Continue`. On a `RuleForEach` rule, `Stop` ends the whole collection at the first failing element.

code

csharp · 37 lines
csharp
using FluentValidation;

public class LineItem
{
    public string Sku { get; set; } = "";
    public int Quantity { get; set; }
}

public class CreateOrderCommand
{
    public string CustomerId { get; set; } = "";
    public List<LineItem> LineItems { get; set; } = new();
}

public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        // Inside each rule: stop at the first failing validator.
        RuleLevelCascadeMode = CascadeMode.Stop;
        // Between rules: keep going, so every bad field is reported.
        ClassLevelCascadeMode = CascadeMode.Continue;

        RuleFor(x => x.CustomerId)
            .NotEmpty()
            .Matches("^C-[0-9]+$");

        // Override for the collection so every bad line item is listed,
        // instead of stopping at the first failing element.
        RuleForEach(x => x.LineItems)
            .Cascade(CascadeMode.Continue)
            .ChildRules(item =>
            {
                item.RuleFor(i => i.Quantity).GreaterThan(0);
            });
    }
}

go deeper

for a junior

Recall that by default every validator and every rule runs, and that Cascade(CascadeMode.Stop) after RuleFor stops a chain at its first failure.

for a middle

Explain the two levels and their properties, the precedence from rule to class to global, and why rule-level Stop protects a Must predicate or an async lookup.

for a senior

Show the edges: class-level Stop can still return several failures, and Stop on RuleForEach ends the whole collection at the first bad element. Know the version 12 migration of StopOnFirstFailure.

for a principal

Decide the team default: rule-level Stop with class-level Continue is the common choice for request validation, and set it once globally rather than per validator.

FluentValidation, the .NET library that declares validation rules as fluent chains in a validator class, runs **every validator of every rule** by default and collects all failures. **Cascade modes** change that. The interview trap is that there are two separate levels, set in different places, and the old single switch was removed in version 12. ## Two levels, two questions A **rule** is one `RuleFor(...)` or `RuleForEach(...)` chain; a **validator** is one check in it, such as `NotEmpty()` or `MustAsync(...)`. The two levels answer different questions: | Level | Question it answers | Where you set it | Default | |---|---|---|---| | Rule level | after a validator in this chain fails, run the rest of the chain? | `.Cascade(CascadeMode.Stop)` on one rule, `RuleLevelCascadeMode` on the class, `ValidatorOptions.Global.DefaultRuleLevelCascadeMode` | `Continue` | | Class level | after a rule fails, run the remaining rules? | `ClassLevelCascadeMode` on the class, `ValidatorOptions.Global.DefaultClassLevelCascadeMode` | `Continue` | `CascadeMode` has exactly two values in version 12: **`Continue`** and **`Stop`**. The more specific setting wins: a `.Cascade(...)` call on a rule overrides the class's `RuleLevelCascadeMode`, which overrides the global default. ## What rule-level Stop buys you Consider a customer ID rule on a create-order command: ```csharp RuleFor(x => x.CustomerId) .Cascade(CascadeMode.Stop) .NotEmpty() .Matches("^C-[0-9]+$") .MustAsync(CustomerExists); ``` With the default `Continue`, an empty ID produces a `NotEmpty` failure **and** a `Matches` failure, and then still calls `CustomerExists`. With `Stop`: - the user sees one meaningful message instead of a cascade of noise; - an expensive or remote check such as `MustAsync` runs only for input that already passed the cheap checks; - a `Must` predicate that would dereference a null value is never reached after `NotNull` fails. Setting `RuleLevelCascadeMode = CascadeMode.Stop` in the validator's constructor applies this to every rule in the class without repeating `.Cascade(...)`, while all rules still run, so the caller still gets one failure per bad field. ## What class-level Stop does, exactly `ClassLevelCascadeMode = CascadeMode.Stop` checks after each rule whether the number of failures grew, and if so stops running further rules. Read it precisely: - It stops **between rules**, not inside one. A rule left at rule-level `Continue` can add two or three failures before the class stops. - A `Custom` rule that calls `AddFailure` twice, or a child validator attached with `SetValidator`, also counts as one rule that may add several failures. - Only with rule level **and** class level both at `Stop` do you get true fail-fast with a single failure from built-in validators. That is usually not what an API wants, because the client then has to fix fields one round-trip at a time. It suits cases where later rules are meaningless after an earlier failure, or validation is costly. ## Collections behave differently On a `RuleForEach` rule, rule-level `Stop` is checked **per element, but stops the whole rule**. When the second line item fails, the remaining line items are not validated at all, and the result reports only the first bad item. Because `RuleLevelCascadeMode` also applies to `RuleForEach` rules, setting it to `Stop` class-wide silently changes collection reporting too. If you want every bad line item listed, leave that rule at `Continue` and put `Cascade(CascadeMode.Stop)` inside a child validator's own rules instead. ## Choosing a default - **API request validation:** rule-level `Stop`, class-level `Continue`. Each field reports one meaningful message, and every bad field is still reported in one response. - **Order checks from cheap to expensive** inside a chain, `NotEmpty` and format checks before `MustAsync`, so rule-level `Stop` shields the lookup from input that is already wrong. - **Class-level `Stop`** only where later rules are meaningless or costly once anything failed, and say so in a comment. - **Set the default once**, through `ValidatorOptions.Global` at application startup, and override it per class or per rule only for a stated reason. Remember the global setting is read when a validator runs, so set it before the first validation. ## What version 12 removed FluentValidation 11 introduced `RuleLevelCascadeMode` and `ClassLevelCascadeMode` and deprecated the old API; **version 12 removed it**: 1. `CascadeMode.StopOnFirstFailure` is gone. It meant "stop inside a rule, continue between rules", so the replacement is `RuleLevelCascadeMode = CascadeMode.Stop` with `ClassLevelCascadeMode = CascadeMode.Continue`, or simply `.Cascade(CascadeMode.Stop)` on the rule. 2. `AbstractValidator.CascadeMode`, which set both levels at once, is gone; set the two properties separately. 3. `ValidatorOptions.Global.CascadeMode` is gone; use the two `Default...CascadeMode` properties. Code that still names any of these does not compile against version 12, which makes the migration mechanical but unavoidable.

  • With FluentValidation 12, how do you migrate a validator that set CascadeMode = CascadeMode.StopOnFirstFailure?
    Replace it with `ClassLevelCascadeMode = CascadeMode.Continue` and `RuleLevelCascadeMode = CascadeMode.Stop`, because StopOnFirstFailure meant stopping inside a rule while continuing between rules. A global `ValidatorOptions.Global.CascadeMode` becomes `DefaultRuleLevelCascadeMode = CascadeMode.Stop`, and `.Cascade(CascadeMode.StopOnFirstFailure)` on a rule becomes `.Cascade(CascadeMode.Stop)`.
  • With FluentValidation, can ClassLevelCascadeMode set to Stop still return more than one failure?
    Yes. The class-level check runs after each whole rule, so the rule that fails first can contribute several failures: a chain left at rule-level `Continue`, a `Custom` rule calling `AddFailure` more than once, or a child validator. Only with rule-level `Stop` as well do built-in validators give a single failure.

A pre-flight checklist with sub-checks under each item. Rule level decides whether, once one sub-check fails, the rest of that item's sub-checks are still read; class level decides whether, once an item has any failure, the crew goes on to the next item at all.

  • Setting ClassLevelCascadeMode to Stop also stops validators inside each rule.
  • Cascade(CascadeMode.Stop) on RuleForEach still validates every element of the list.
  • The default cascade mode is Stop, so only the first failure is ever reported.
  • CascadeMode.StopOnFirstFailure is still the recommended option in version 12.
  • Rule-level Stop skips the remaining rules in the validator class.

Assumes FluentValidation 12, which removed CascadeMode.StopOnFirstFailure, AbstractValidator.CascadeMode and ValidatorOptions.Global.CascadeMode after deprecating them in 11.