An illegal state is a value your program can represent even though it violates the domain’s rules. It often begins with an imprecise type: a String used as a UUID can hold infinitely many values that are not valid IDs. The mismatch forces preconditions, checks, tests, and defensive code to compensate for a representation that permits the wrong thing. section 1.2
The practical warning sign is contextual meaning: fields are populated only for certain flag or enum values, nullable when absent, and unsafe when read without first rechecking the context. Constructor validation can block these combinations at creation, but poorly modeled values still spread defensive conditions and null risks through every consumer. section 4.1.4 section 4.1.6
Checklist completion is not template data
A travel-checklist template with Step(name, isCompleted) permits a nonsensical template in which “bring socks” is already complete. Removing completion from Step and recording it in a Status tied to a particular checklist Instance separates static template data from work performed during a run. section 4.1.3
Repair the model rather than merely refactoring its fields. Group attributes that always belong together into a dedicated type, then represent alternatives with separate types. Completed can carry who and when it was completed; NotStarted carries neither; Skipped carries its own actor, time, and rationale. Those combinations remove states that validation previously had to reject. section 4.2.1 section 4.8
Listing 4.17 Guarding against missing (or not missing!) attributes during construction
record Status(
Instance instance,
Step step,
boolean isCompleted,
User completedBy,
Instant completedOn
) {
Status {
if (isCompleted && (completedBy == null || completedOn == null)) {
throw new IllegalArgumentException( #A
"completedBy and completedOn cannot be null " + #A
"when isCompleted is true" #A
); #A
}
if (!isCompleted && (completedBy != null || completedOn != null ) {
throw new IllegalArgumentException( #B
"completedBy and completedOn cannot be populated " + #B
"when isCompleted is false" #B
);
}
}
}The constructor guards show the cost of one record whose fields have different validity rules for completed and uncompleted states. section 4.1.4
Illegal states also arise through process, not only field layout. Partial construction can bypass earlier validation: a cart item gains a required seller ID after processing has started, producing duplicate-key behavior. Surface hidden knowledge, work backward from invariants, and make a data type the guarded boundary for validated values. section 9.2.4 section 9.6

