JSF Validation Converters and Messages That Users Understand
Understand JSF conversion and validation: converters, built in validators, Bean Validation, custom validators and messages, and why errors skip the model.

Every form field in JSF travels through two steps before it touches your bean: conversion and validation. Most "the method is not called" bugs live in these two steps, because a failure in either one silently stops the request from reaching your code. This guide explains conversion with built-in and custom converters, validation with built-in validators, Bean Validation and a custom validator, what happens on failure, how to show messages that users understand and how to override the default text. It targets Jakarta Faces 4 on Jakarta EE 10 and later. The phases themselves are described in the JSF lifecycle.
Conversion
<h:inputText id="date" value="#{booking.checkIn}" label="Check-in">
<f:convertDateTime pattern="yyyy-MM-dd" type="localDate" />
</h:inputText>
<h:message for="date" />The browser always sends a string. JSF has converters for numbers, dates and enums, and it picks one from the property type of the bound value. A failure produces a message such as Check-in: '2026-13-40' could not be understood as a date and the phase ends. Giving the component a label makes that message readable; without it the message names the component id, which means nothing to a user. A custom converter handles your own types:
@FacesConverter(forClass = Sku.class)
public class SkuConverter implements Converter<Sku> {
public Sku getAsObject(FacesContext ctx, UIComponent c, String value) {
if (value == null || value.isBlank()) return null;
try {
return Sku.parse(value);
} catch (IllegalArgumentException e) {
throw new ConverterException(new FacesMessage("Not a valid SKU: " + value));
}
}
public String getAsString(FacesContext ctx, UIComponent c, Sku value) {
return value == null ? "" : value.toString();
}
}getAsObject turns the submitted string into your type and getAsString does the reverse when the page is rendered. Return null for an empty input and let validation decide whether a value is required. Throw a ConverterException with a message the user can act on, not a stack trace. forClass registers the converter for every property of that type, so you do not repeat it on each field.
Validation
<h:inputText id="qty" value="#{line.quantity}" required="true" requiredMessage="Enter a quantity">
<f:validateLongRange minimum="1" maximum="999" />
</h:inputText>Built-in validators cover length, range, regular expression and required. Validators run only after conversion succeeds, so a quantity of abc fails the converter first and the range validator never runs. A subtle point: an empty field is passed to validators as null or an empty string depending on a context parameter, so the combination of required and an optional field can behave unexpectedly. Check the jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL setting if an optional field fails validation when left blank.
Bean Validation
public class Line {
@Min(1) @Max(999) private int quantity;
@NotBlank @Size(max = 60) private String note;
}Faces integrates with Jakarta Validation, so annotated properties are checked during the same phase without extra markup. The rules then live on the model and apply wherever the object is validated, not only on this page. Combine both styles when a rule is only about presentation, such as a required field on one form. The annotation approach is the same as in Spring request bodies and Jakarta Validation.
A custom validator
@FacesValidator("uniqueEmail")
public class UniqueEmailValidator implements Validator<String> {
@Inject UserRepository users;
public void validate(FacesContext ctx, UIComponent c, String email) {
if (users.existsByEmail(email)) {
throw new ValidatorException(new FacesMessage(FacesMessage.SEVERITY_ERROR, "Email already registered", null));
}
}
}Use it with <f:validator validatorId="uniqueEmail" />. In Faces 4, injection works in validators and converters when the annotation attribute managed = true is set on the annotation, so check your version's rules. A uniqueness check still needs a database constraint, because two users can pass validation at the same moment, and the validator only gives a friendlier message in the common case.
What happens on failure
When any component fails conversion or validation, JSF skips the update-model and invoke-application phases and redisplays the page with messages. Your action method is never called and the bean is untouched. That is by design, and it is the reason a button "does nothing" when a hidden required field is empty: the failure message exists, but nothing on the page shows it. Add an h:messages element at the top of the form, at least during development, and the mystery disappears. In AJAX requests, make sure the messages component is inside the update or render list, or the message is created but never shown.
Messages
<h:messages globalOnly="false" showDetail="true" styleClass="messages" />
<h:message for="qty" styleClass="error" />h:message shows messages for one component, next to the field, and h:messages shows all of them. Show the detail text, because the summary alone is often too terse. Override the built-in wording in a bundle declared in faces-config.xml as <message-bundle>, using keys such as jakarta.faces.converter.DateTimeConverter.DATE in Faces 4 (older versions used the javax.faces. prefix). A resource bundle also gives you translations, and the messages a user reads should be written like the rest of the interface, with the field name and the fix: "Enter a quantity between 1 and 999".
Testing
Test converters and validators as plain classes, with a few inputs including null, blank and boundary values, since they need no container beyond a stub FacesContext. For the page behaviour, a browser-level test that submits an invalid form and checks that the message appears covers the wiring. Write the test for the silent failure too: submit the form with a hidden invalid field and assert that a message is visible.
Cross-field validation
Rules that involve two fields, such as "the end date must follow the start date" or "the two passwords must match", do not fit a validator attached to one component. Two approaches work. A class-level Bean Validation constraint on the bean validates both properties together and reports a global message. Or a validator on the second component reads the first through an attribute passed with <f:attribute name="startDate" value="#{startInput}"/> and compares. The bean-level constraint is easier to test and reuse. Whichever you pick, show the message next to the second field so the user knows where to look.
Immediate versus deferred checks
Components with immediate="true" run conversion and validation in an earlier phase, which is how a Cancel button skips validation of the form. If a Cancel button fails with validation messages from fields the user never touched, set immediate="true" on the button, and be aware that it changes the order of processing for that component and its action. Use it sparingly, because the interaction with other components is a frequent source of confusion.
Where validation stops
Validation protects the shape of input, not authorisation or business rules, which belong in the service layer. For partial updates of one field, f:ajax with execute limits what is validated, see AJAX in JSF. Values that never reach the bean are covered in values not updating. The reference is the Jakarta Faces specification, and PrimeFaces validation shows client-side options.


