Spring Batch flow status: distinguish step failure from job restartability

Read both levels

A reconciliation step can report a review-required exit code while the job reaches a configured terminal state. ExitStatus describes the outcome used by flow transitions; BatchStatus records lifecycle state such as COMPLETED, FAILED or STOPPED. A transition that ends the job as COMPLETED makes that job instance non-restartable, even if a preceding step failed. Use a failing or stopped transition when an operator must correct data and resume the same instance. Running execution recovery is a separate case after abrupt process death.

Define the operational contract

For settlement imports, treat rejected business rows differently from unavailable infrastructure. A small accepted rejection count might finish as COMPLETED with a review flag in a durable summary. A database outage should leave a FAILED job eligible for restart after repair. Record exact counts and keys in business tables, not only a custom exit string, because repository metadata may later be archived. Rejected-row quarantine covers the durable review path.

Assert the next launch

Build tests for each transition: normal completion, review-required completion, failure and deliberate stop. Inspect both the job and step statuses, then actually relaunch with the same identifying parameters. The expected behavior should be explicit: completed instances reject a duplicate launch, while failed or stopped instances follow their configured restart path. A single status assertion cannot prove restartability.

Implementation contract

JobExecution execution = jobLauncher.run(settlementJob, identifyingParameters);
BatchStatus lifecycle = execution.getStatus();
String outcome = execution.getExitStatus().getExitCode();
assertThat(lifecycle).isEqualTo(BatchStatus.FAILED);
assertThat(outcome).isEqualTo("FAILED");
// Relaunch the same identifying parameters only after the failure is repaired.

Cost and verification

Flow transitions add no meaningful item-processing cost, but incorrect terminal status can force a new instance and manual reconciliation of already committed output.

Common Mistakes

• Do not mark a recoverable failure COMPLETED merely to suppress an alert.
• Do not infer job restartability from one step’s ExitStatus.
• Do not change identifying parameters to bypass a failed execution without reconciling writes.

Read next

Spring Batch orphaned STARTED execution: inspect before relaunch, Spring Batch job identity: a manifest ID defines restart versus a new run, Spring Batch SkipListener: persist a rejection key with the skipped row, Spring Batch parallel flows: make dependency order explicit, Spring Batch restart boundaries: recorded failure versus abrupt process loss.

Related Boot contract

Spring Boot process exit codes: make job failure visible to the scheduler.