skip to content

What exactly happens at startup when a validated @ConfigurationProperties value violates a constraint?

level: middleimportance: should knowfreq 35%

answer

  1. context refresh -> binding -> validate
  2. BindValidationException root cause
  3. APPLICATION FAILED TO START report
  4. all violations reported at once
  5. non-zero exit, fail-fast deploy

basics

~20 s

Binding fails, so the bean can't be created and the Spring application context fails to start. Boot logs a formatted error naming the property, the offending value, and the reason, then the process exits non-zero.

solid answer

~40 s

Validation runs while Boot binds the properties bean during context refresh. A constraint violation throws a validation error that propagates up as a bean-creation failure, so the ApplicationContext fails to start and the JVM exits with a non-zero code — this is the fail-fast behaviour. The root cause is a BindValidationException (org.springframework.boot.context.properties.bind.validation.BindValidationException), typically wrapped by Boot's BindException / ConfigurationPropertiesBindException. Boot renders a readable report listing each failing property, its resolved value, its origin (which file/line or env var), and the failed constraint message. Because it happens before the app serves traffic, you catch misconfiguration at deploy time rather than as a runtime NPE or bad request later. All violations for that bean are reported together, not just the first, so operators can fix everything in one pass.

code

yaml · 16 lines
yaml
# application.yml — this value is out of the @Min(1)/@Max(65535) range
app:
  mail:
    host: smtp.example.com
    port: 70000

# Result at startup:
# ***************************
# APPLICATION FAILED TO START
# ***************************
# Binding to target ...MailProperties failed:
#     Property: app.mail.port
#     Value: "70000"
#     Origin: class path resource [application.yml] - 4:11
#     Reason: must be less than or equal to 65535
# (root cause: BindValidationException) -> context does not start

go deeper

for a junior

Know that a violation stops the app from starting and prints a clear error.

for a middle

Name BindValidationException, the fail-fast semantics, and that all violations are reported with origin.

for a senior

Explain the wrapping exception chain and the FailureAnalyzer-produced report, plus lazy-bean caveats.

for a principal

Decide which invariants deserve boot-time fail-fast vs. graceful degradation, and how that plays with rolling deploys.

## The lifecycle `@ConfigurationProperties` beans are bound during **application context refresh**, early in startup. When the target class is `@Validated`, Boot's `ConfigurationPropertiesBindingPostProcessor` runs the JSR-380 constraints via a `ConfigurationPropertiesJsr303Validator` immediately after binding each property object. ## What is thrown A constraint failure produces a **`BindValidationException`** (`org.springframework.boot.context.properties.bind.validation.BindValidationException`). Boot wraps it — you'll typically see a **`BindException`** (`org.springframework.boot.context.properties.bind.BindException`) and/or a **`ConfigurationPropertiesBindException`** (`org.springframework.boot.context.properties.ConfigurationPropertiesBindException`) in the chain, ultimately surfacing as a Spring bean-creation failure (`BeanCreationException`/`UnsatisfiedDependencyException`). The net effect: **the ApplicationContext fails to refresh and the application does not start** (non-zero exit). ## The error report Boot prints a well-formatted message, e.g.: ``` *************************** APPLICATION FAILED TO START *************************** Binding to target ... failed: Property: app.mail.port Value: "70000" Origin: class path resource [application.yml] - 12:11 Reason: must be less than or equal to 65535 ``` It reports **every** violation on the bean at once (not just the first), with the property path, the resolved value, its **origin** (source file + line, or the environment variable name), and the constraint message. ## Why this matters (fail-fast) The whole point of validating bound config is **fail-fast at startup**: a missing required value or an out-of-range number aborts the deploy loudly and legibly, instead of causing a `NullPointerException`, silent default, or corrupted behaviour once the app is live. In containerized/CI deploys the non-zero exit stops a bad rollout. ## Gotchas - **Lazy beans**: if a `@ConfigurationProperties` bean is only created lazily, its validation may not run until first use — prefer eager binding for config you want checked at boot. - **Missing vs. blank**: `@NotNull` catches a missing key; a present-but-empty string needs `@NotBlank`/`@NotEmpty`. - **Type conversion vs. constraint**: a non-numeric value for an `int` fails during *conversion* (a bind error), separate from a JSR-380 *constraint* failure — both abort startup but come from different stages. - The formatted report is produced by Boot's `FailureAnalyzer` infrastructure (a bind-validation failure analyzer).

  • Does Boot stop at the first bad property or report all of them?
    It collects and reports all constraint violations for that properties bean together, so operators can fix every problem in one pass rather than rebooting repeatedly.

saying these in an interview costs you the question

  • Claiming the app starts and only logs a warning on validation failure
  • Thinking only the first violation is reported
  • Confusing a type-conversion bind error with a JSR-380 constraint violation

context

resolving links…