Troubleshooting
Quick map
| Symptom | Likely cause |
|---|---|
AsyncValidatorInvokedSynchronouslyException |
Sync Validate on an async-only validator. |
InvalidOperationException mentioning PreValidateAsync |
Async hook configured; call ValidateAsync. |
| Validation silently does nothing | Validator not registered as IValidator<T>. |
| Rule set ignored | Name mismatch or rules outside the set. |
| Property filter has no effect | Generated rules are flat; property filters target fluent member groups. |
| OpenAPI schema has no constraints | Transformer/document mismatch or naming policy. |
| Blazor message on the wrong field | Unsupported collection shape or null model graph. |
| Localization returns the fallback | Missing pack/key or a second provider. |
ArgumentException from In/NotIn |
Empty allowed/disallowed set. |
RegexMatchTimeoutException |
Pattern exceeded the one-second timeout. |
AsyncValidatorInvokedSynchronouslyException
The validator has async rules but no sync rules. Use ValidateAsync or add synchronous rules.
VAL0016 warns at compile time for [AsyncOnlyValidator] receivers.
InvalidOperationException from an async pre-validation hook
PreValidateAsync makes the synchronous path throw:
An asynchronous PreValidate hook is configured on this validator; call ValidateAsync instead.
Call ValidateAsync, or move the check into a custom rule that runs on the async path.
Validation silently does nothing
- No validator is registered for the request type.
- The validator is registered as a concrete type but the host resolves
IValidator<T>. - The request type differs from the validator’s
T. - The host adapter is not attached (
AddRequestValidation<T>,AddMvcValidation,AddValidationPipeline).
Register IValidator<T> explicitly.
Rule sets are ignored
- Set names are case-insensitive but must match exactly otherwise.
- When rule sets are named, ungrouped rules do not run unless
defaultis included. ruleSets: nullmeans “all rules”, not “default rules only”.ValidationCallOptions.RuleSetsselects sets for that call;nullor empty means all rules.ExcludeRuleSets("default")removes ungrouped rules.
Property filters have no effect
IncludeProperties / ExcludeProperties work on fluent and generated validators. Check that the
member name matches exactly (ordinal), that nested members are targeted as a unit, and that the
validator implements IValidationOptionsValidator<T>; a validator without that contract throws
NotSupportedException instead of silently ignoring the options.
OpenAPI schema has no constraints
- The transformer is attached to a different document name.
- The request type is not registered in
AddSchemaConstraintsFromValidators. - A custom JSON naming policy hides the member name.
- The validator was never described (generated validators need the generator to run).
Register the validator and use the default v1 document or attach the transformer to the custom
document. See JSON Schema, OpenAPI, and client rules.
Blazor messages appear on the wrong field
Nested paths resolve through the model graph. Confirm the model is not null and the collection is an
array or IList; other collection shapes fall back to the root identifier.
Localization returns the fallback message
- The culture has no pack and no parent/invariant fallback.
- The message key is not present in the pack.
- A second provider was registered; the platform enforces exactly one provider.
ValidationError.Messageis null and the caller did not resolveMessageKey.
Use AddDefaultMessagePacks(options => ...) for overrides instead of a second provider, and resolve
MessageKey through LocalizeValidationErrorAsync.
ArgumentException from In or NotIn
Both rules reject an empty value set at construction time. Supply at least one value, or use a different rule when “anything” is allowed.
RegexMatchTimeoutException
Matches(pattern) compiles the regex with a one-second timeout. A timeout propagates to the caller.
Keep patterns bounded, avoid nested quantifiers on untrusted input, and handle the exception at the
boundary if the input is adversarial.
ValidationException with an inner exception
A lifecycle hook threw. PreValidate, PreValidateAsync, OnFailure, and OnFailureAsync wrap
non-cancellation exceptions in ValidationException. Inspect InnerException and fix the hook.
OperationCanceledException is not wrapped.
Trim or AOT warnings from AddGeneratedValidators
The method is annotated [RequiresUnreferencedCode]. Register validators explicitly in trimmed or
Native AOT applications:
services.AddScoped<CustomerValidator>();
services.AddScoped<IValidator<Customer>, CustomerValidator>();
Duplicate validation
Both the host filter and manual code run the validator. Validate once at the boundary. If you need a
manual check inside a handler, remove the endpoint/action filter or opt out with
[SkipJeninnetValidation].
Client rules are missing a validator
ClientRulesOptions.IncludedValidatorsis non-empty and does not contain the validator name.- The validator was not passed to
ClientRulesWriter. - The build-time catalog is disabled; set
JeninnetEmitClientRules=trueand add<CompilerVisibleProperty Include="JeninnetEmitClientRules" />. - The client cached an old payload; check
schemaVersion.
NU1903 on build
The OpenApi package and the AOT smoke harness suppress vendor-gated advisories for build-time dependencies. See the package README and AOT and trimming.
Getting help
Open an issue with the validator definition, the input, the expected result, and the actual result. For analyzer issues, include the diagnostic ID and the smallest reproducer.