A hash map (dict, hash table) stores key-value pairs and finds any key in roughly O(1) time. The trick is turning the key into an array index.

The core idea

1. A hash function converts your key into a number.
2. That number maps to a bucket (an index in an internal array).
3. The value gets stored in that bucket — so lookup goes straight there.

def bucket_index(key, size):
    return hash(key) % size   # turn key into an array index

# Conceptually:
buckets = [[] for _ in range(8)]
def put(key, value):
    buckets[bucket_index(key, 8)].append((key, value))

Collisions

Two keys can land in the same bucket. Maps handle this by chaining (storing a small list per bucket) or open addressing (probing for the next free slot). With a good hash function, collisions stay rare and lookups stay fast.

When it slows down

If too many keys crowd into too few buckets, lookups degrade toward O(n). Real implementations resize (rehash into a bigger array) once they get too full, keeping operations near constant time on average.

TL;DR: A hash map turns keys into array indices via a hash function, giving average O(1) lookup — collisions and resizing are the details that keep it honest.

Reach for a dict whenever you find yourself scanning a list to find one item.

How Hash Maps Work 🗺️ was originally published in The 60-Second Programmer on Medium, where people are continuing the conversation by highlighting and responding to this story.

This article explains why the obvious solution (two-phase commit) fails at scale, the two saga styles, how compensation actually works, the failure-handling vocabulary you need (semantic locks, retriable vs compensatable steps, isolation anomalies), and concrete Spring Boot 3.x code for both choreography and orchestration.

Why two-phase commit fails at scale

Two-phase commit (2PC) is the textbook answer to distributed atomicity. A coordinator asks every participant to prepare (phase 1); if all vote yes, it tells them to commit (phase 2). It genuinely gives you ACID across nodes. It also has properties that make it a poor fit for internet-scale microservices.

• Synchronous coupling and blocking. Between prepare and commit, each participant holds locks on the affected rows. Every service in the transaction must be up, reachable, and fast at the same time. The transaction’s availability becomes the product of every participant’s availability — the opposite of why you split into services.
• The coordinator is a failure point. If the coordinator crashes after participants vote “yes” but before it broadcasts the decision, participants are stuck holding locks, unable to safely commit or abort. This is the classic 2PC blocking problem. Recovery requires a durable coordinator log and careful timeout handling.
• It does not scale with latency. Locks held for the duration of a network round trip kill throughput under contention. A hot row (a popular SKU’s stock count) becomes a global serialization point.
• Heterogeneity. 2PC needs an XA-capable resource manager on every participant. Your payment provider is an HTTP API. Kafka is not an XA resource in any practical sense. A third-party shipping service will never enlist in your transaction. The moment one participant cannot speak XA, 2PC is off the table.

The deeper issue is philosophical. Microservices buy you autonomy — independent deployment, independent scaling, independent failure. 2PC reintroduces a tight temporal coupling that throws that autonomy away. Sagas make the opposite trade: they give up immediate, global isolation in exchange for availability and loose coupling.

What a saga actually is

A saga is a sequence of local transactions. Each local transaction updates a single service’s database and publishes a message (an event or a command) that triggers the next local transaction. There is no global lock and no global commit. Each step commits independently and immediately.

Because there is no rollback across services, a saga handles failure differently from a database. If step 4 fails, you cannot “roll back” steps 1–3 — they already committed. Instead you run compensating transactions: new local transactions that semantically undo the effects of the earlier committed steps, in reverse order.

So a saga has two flavors of step:

• Forward (compensatable) transactions — T1, T2, ..., Tn — the happy path.
• Compensating transactions — C1, C2, ..., Cn-1 — the undo path. Ci semantically reverses Ti.

The guarantee a saga gives you is: either all forward transactions complete, or a subset of forward transactions complete and the corresponding compensations run. That is atomicity, but not isolation. We will come back to the isolation hole, because it is where most people get hurt.

The worked example: Order → Payment → Inventory

Throughout, we use a single scenario. A customer places an order. The system must:

1. Create the order in PENDING state (Order Service).
2. Charge the customer (Payment Service).
3. Reserve stock for the line items (Inventory Service).
4. Mark the order CONFIRMED (Order Service).

If payment fails, we cancel the order. If inventory reservation fails, we refund the payment and cancel the order. Here is the flow with its compensation arrows.

Happy path (forward transactions)
   ───────────────────────────────────────────────►
 ┌─────────┐   ┌─────────┐   ┌───────────┐   ┌─────────┐
 │ ORDER   │   │ PAYMENT │   │ INVENTORY │   │ ORDER   │
 │ create  │──►│ charge  │──►│ reserve   │──►│ confirm │
 │ (T1)    │   │ (T2)    │   │ (T3)      │   │ (T4)    │
 └─────────┘   └─────────┘   └───────────┘   └─────────┘
      ▲             ▲              │
      │             │              │ T3 fails (out of stock)
      │  C1         │  C2          ▼
 ┌─────────┐   ┌─────────┐   ┌───────────┐
 │ ORDER   │◄──│ PAYMENT │◄──│   (no-op: │
 │ cancel  │   │ refund  │   │  nothing  │
 │ (C1)    │   │ (C2)    │   │ reserved) │
 └─────────┘   └─────────┘   └───────────┘
   ◄───────────────────────────────────────
   Compensation path (reverse order)

The key insight: compensations run in reverse order of the forward steps that succeeded. If T3 fails, we compensate T2 (refund) then T1 (cancel order). T3 itself produced no committed effect, so it needs no compensation.

Choreography vs orchestration

There are two ways to coordinate the steps. They are not interchangeable — the choice shapes coupling, observability, and how hard the failure logic is to reason about.

Choreography is decentralized. Each service listens for events and reacts by doing its local work and emitting its own event. There is no central brain. Order Service emits OrderCreated; Payment Service hears it, charges, emits PaymentCompleted; Inventory Service hears that, reserves, emits StockReserved; Order Service hears that and confirms. The "workflow" is an emergent property of who subscribes to what.

Orchestration is centralized. A dedicated orchestrator (a saga execution coordinator) sends explicit commands (ChargePayment, ReserveStock) and waits for replies. The orchestrator holds the state machine: it knows what step we are on, what to do next, and which compensations to fire on failure.

| Dimension | Choreography | Orchestration |
|---|---|---|
| Coordination | Decentralized, event-driven | Central orchestrator with explicit commands |
| Coupling | Looser at runtime, tighter conceptually (everyone knows the event contract) | Services coupled to orchestrator, not to each other |
| Workflow visibility | Implicit, scattered across services | Explicit, in one place — easy to read |
| Adding a step | Risk of cyclic event dependencies; hard to see full flow | Edit the orchestrator state machine |
| Failure/compensation logic | Spread across services, easy to get subtly wrong | Centralized, easier to test exhaustively |
| Single point of failure | None inherent | Orchestrator (mitigated by persisting saga state) |
| Best for | Short sagas (2–4 steps), few participants | Long or complex sagas, many branches |

Rule of thumb: choreography for simple, short flows where the event chain is obvious; orchestration once you have branching, more than ~4 steps, or you need a human to be able to answer “what state is order #4471 in?” without grepping five services.

Choreography with Spring Boot 3.x and Kafka

We use Kafka as the event backbone. The critical correctness concern is the dual-write problem: a service must update its own database and publish an event atomically. If it commits the DB row but crashes before publishing, the saga stalls. The standard fix is the transactional outbox: write the event into an outbox table in the same local transaction as the business change, then a separate relay publishes from the outbox to Kafka.

First, the order entity and the outbox-backed event write. Using Spring’s ApplicationEventPublisher lets us decouple, but the outbox row is what guarantees durability.

@Entity
@Table(name = "orders")
public class Order {
    @Id
    private UUID id;

    @Enumerated(EnumType.STRING)
    private OrderStatus status; // PENDING, CONFIRMED, CANCELLED

    private String customerId;
    private BigDecimal amount;

    @Version
    private long version; // optimistic locking guards concurrent updates

    // getters/setters/constructors omitted for brevity
}

@Entity
@Table(name = "outbox")
public class OutboxEvent {
    @Id
    private UUID id;
    private String aggregateType; // "order"
    private String aggregateId;   // order id
    private String type;          // "OrderCreated"
    @Column(columnDefinition = "jsonb")
    private String payload;
    private Instant createdAt;
    // getters/setters omitted
}

@Service
public class OrderService {

    private final OrderRepository orders;
    private final OutboxRepository outbox;
    private final ObjectMapper mapper;

    public OrderService(OrderRepository orders, OutboxRepository outbox, ObjectMapper mapper) {
        this.orders = orders;
        this.outbox = outbox;
        this.mapper = mapper;
    }

    @Transactional
    public Order placeOrder(String customerId, BigDecimal amount) {
        Order order = new Order(UUID.randomUUID(), OrderStatus.PENDING, customerId, amount);
        orders.save(order);

        // Same transaction as the order insert: no dual-write hole.
        var event = new OrderCreated(order.getId(), customerId, amount);
        outbox.save(new OutboxEvent(
                UUID.randomUUID(), "order", order.getId().toString(),
                "OrderCreated", writeJson(event), Instant.now()));
        return order;
    }

    private String writeJson(Object o) {
        try {
            return mapper.writeValueAsString(o);
        } catch (JsonProcessingException e) {
            throw new IllegalStateException("event serialization failed", e);
        }
    }
}

In production you would typically let Debezium tail the outbox table's transaction log straight into Kafka. If you do not want CDC, a simple polling relay is fine for moderate volumes:

@Component
public class OutboxRelay {

    private final OutboxRepository outbox;
    private final KafkaTemplate<String, String> kafka;

    public OutboxRelay(OutboxRepository outbox, KafkaTemplate<String, String> kafka) {
        this.outbox = outbox;
        this.kafka = kafka;
    }

    @Scheduled(fixedDelay = 500)
    @Transactional
    public void publishPending() {
        List<OutboxEvent> batch = outbox.findTop100ByOrderByCreatedAtAsc();
        for (OutboxEvent e : batch) {
            // topic name derived from aggregate type; key = aggregateId for ordering
            kafka.send(e.getAggregateType() + "-events", e.getAggregateId(), e.getPayload());
            outbox.delete(e);
        }
    }
}

Note the Kafka key is the aggregate id. That preserves per-order ordering on the topic partition, which matters: you do not want PaymentCompleted overtaking OrderCreated for the same order.

Now the Payment Service consumes OrderCreated and reacts. The consumer must be idempotent — Kafka guarantees at-least-once delivery, so the same event can arrive twice.

@Component
public class PaymentEventHandler {

    private final PaymentRepository payments;
    private final ProcessedEventRepository processed;
    private final OutboxRepository outbox;
    private final ObjectMapper mapper;

    // constructor omitted

    @KafkaListener(topics = "order-events", groupId = "payment-service")
    @Transactional
    public void onOrderEvent(ConsumerRecord<String, String> record) throws Exception {
        JsonNode node = mapper.readTree(record.value());
        if (!"OrderCreated".equals(node.get("type").asText())) {
            return; // not our concern
        }
        var event = mapper.treeToValue(node, OrderCreated.class);

        // Idempotency guard: dedupe by event id in the same transaction.
        if (processed.existsById(event.eventId())) {
            return;
        }
        processed.save(new ProcessedEvent(event.eventId(), Instant.now()));

        try {
            payments.save(Payment.charge(event.orderId(), event.amount()));
            emit("PaymentCompleted", new PaymentCompleted(event.orderId(), event.amount()));
        } catch (PaymentDeclinedException ex) {
            // No money moved; emit a failure event to trigger compensation upstream.
            emit("PaymentFailed", new PaymentFailed(event.orderId(), ex.getReason()));
        }
    }

    private void emit(String type, Object payload) {
        outbox.save(new OutboxEvent(UUID.randomUUID(), "payment",
                ((HasOrderId) payload).orderId().toString(), type, writeJson(payload), Instant.now()));
    }
    // writeJson omitted
}

Inventory then listens for PaymentCompleted and tries to reserve stock. On failure it emits StockReservationFailed, which Payment Service consumes to issue a refund (its compensation, C2), and Order Service consumes to cancel the order (C1). Each compensation is itself a local transaction that emits its own event — the compensation chain is just more choreography running backwards.

The danger of choreography is visible here: there is no single place that says “the order saga has these four steps and these three compensations.” A new engineer must trace topic subscriptions across three repos. This is exactly the pain orchestration removes.

Orchestration with an explicit coordinator

In orchestration, the orchestrator owns a persisted state machine. It sends commands and consumes replies. Persisting saga state is non-negotiable: if the orchestrator restarts mid-saga, it must resume from where it left off, not from the start.

@Entity
@Table(name = "order_saga_state")
public class OrderSagaState {
    @Id
    private UUID sagaId;
    private UUID orderId;

    @Enumerated(EnumType.STRING)
    private SagaStep step; // STARTED, PAYMENT_REQUESTED, STOCK_REQUESTED, COMPLETED, COMPENSATING, FAILED

    private boolean paymentCharged; // track what must be compensated
    private boolean stockReserved;

    @Version
    private long version;
    // getters/setters omitted
}

@Service
public class OrderSagaOrchestrator {

    private final OrderSagaStateRepository state;
    private final CommandGateway commands; // thin wrapper over KafkaTemplate for command topics

    public OrderSagaOrchestrator(OrderSagaStateRepository state, CommandGateway commands) {
        this.state = state;
        this.commands = commands;
    }

    @Transactional
    public void start(UUID orderId, BigDecimal amount, String customerId) {
        var saga = new OrderSagaState(UUID.randomUUID(), orderId, SagaStep.PAYMENT_REQUESTED);
        state.save(saga);
        commands.send("payment-commands",
                new ChargePayment(saga.getSagaId(), orderId, customerId, amount));
    }

    @KafkaListener(topics = "payment-replies", groupId = "order-orchestrator")
    @Transactional
    public void onPaymentReply(PaymentReply reply) {
        OrderSagaState saga = state.findById(reply.sagaId()).orElseThrow();
        if (reply.success()) {
            saga.setPaymentCharged(true);
            saga.setStep(SagaStep.STOCK_REQUESTED);
            commands.send("inventory-commands",
                    new ReserveStock(saga.getSagaId(), saga.getOrderId()));
        } else {
            // Payment failed: nothing to compensate yet, just fail the order.
            saga.setStep(SagaStep.FAILED);
            commands.send("order-commands", new CancelOrder(saga.getOrderId()));
        }
    }

    @KafkaListener(topics = "inventory-replies", groupId = "order-orchestrator")
    @Transactional
    public void onInventoryReply(InventoryReply reply) {
        OrderSagaState saga = state.findById(reply.sagaId()).orElseThrow();
        if (reply.success()) {
            saga.setStockReserved(true);
            saga.setStep(SagaStep.COMPLETED);
            commands.send("order-commands", new ConfirmOrder(saga.getOrderId()));
        } else {
            // Stock failed: compensate in reverse order. Refund first, then cancel.
            saga.setStep(SagaStep.COMPENSATING);
            if (saga.isPaymentCharged()) {
                commands.send("payment-commands",
                        new RefundPayment(saga.getSagaId(), saga.getOrderId()));
            }
            commands.send("order-commands", new CancelOrder(saga.getOrderId()));
        }
    }
}

The orchestrator reads top-to-bottom like the business process. Adding a fraud-check step is a localized edit to this class plus one new command/reply pair — you do not touch the event subscriptions of unrelated services. The cost is that the orchestrator is now a component every order flows through; you mitigate its single-point-of-failure risk by running multiple instances against the shared, persisted saga state with optimistic locking (@Version).

For non-trivial systems, do not hand-roll this state machine. Spring Statemachine, Axon Framework’s saga support, Eventuate Tram Sagas, or a workflow engine like Temporal or Camunda give you persistence, retries, and timeouts out of the box. The hand-rolled version above is for understanding what those libraries are doing.

Failure handling: the part that is actually hard

The forward path is easy. The value of the saga pattern is in the failure semantics, and there is real vocabulary here.

Retriable vs compensatable steps

Eventuate’s model (from Chris Richardson’s Microservices Patterns) classifies each step:

• Compensatable transactions — steps that may need to be undone because a later step can fail. (Create order, Charge payment.)
• Pivot transaction — the point of no return. Once it commits, the saga will complete forward; there is no going back. (Often the last step that could fail for a business reason — e.g. Reserve stock if everything after it is guaranteed to succeed.)
• Retriable transactions — steps after the pivot that must eventually succeed and are therefore only ever retried, never compensated. (Confirm order, Send confirmation email.)

Why this matters: you design the saga so that everything that can fail for a business reason happens before the pivot, and everything after the pivot is something you can guarantee by retrying. Send confirmation email must never be allowed to fail the whole order — it is retriable. You do not refund a customer because an SMTP server was briefly down.

Idempotency and retries

Every consumer must be idempotent because messaging is at-least-once. We saw the ProcessedEvent dedupe table above. Compensations must also be idempotent — a refund command might be delivered twice, and you must refund only once. Track compensation state explicitly (the paymentCharged flag), and make the refund a no-op if it has already run.

Compensations themselves can fail (the payment gateway is down during a refund). The rule: compensations must be retried until they succeed, with backoff and a dead-letter queue plus alerting as the last resort. A compensation that gives up leaves the system in an inconsistent state — money taken, order cancelled. This is the worst outcome and warrants a human.

Semantic locks: closing the isolation hole

Here is the uncomfortable truth: sagas are not isolated. While a saga is in flight, its partial, uncommitted-from-a-business-view changes are visible to everyone. A monolithic transaction would hide them until commit. The classic anomalies (from the same literature):

• Lost updates — saga A overwrites a change made by saga B without seeing it.
• Dirty reads — saga B reads data that saga A has changed but later compensates away. B made a decision on data that “never really happened.”
• Fuzzy / non-repeatable reads — different steps of the same saga read the same data and get different answers because another saga modified it in between.

The standard countermeasure is the semantic lock: instead of locking rows at the database level, you mark the affected business entity with an application-level flag indicating an in-progress saga. The Order.status = PENDING is exactly this — it tells the rest of the system "this order is not finished; do not treat it as confirmed." A stock reservation is another semantic lock: the quantity is moved to a RESERVED bucket, visible as unavailable, but not yet SOLD. If the saga compensates, the reservation is released.

@Service
public class InventoryService {

    private final StockRepository stock;

    public InventoryService(StockRepository stock) {
        this.stock = stock;
    }

    @Transactional
    public boolean reserve(UUID orderId, String sku, int qty) {
        // Optimistic-locked read-modify-write avoids lost updates on hot SKUs.
        StockItem item = stock.findBySku(sku).orElseThrow();
        if (item.available() < qty) {
            return false; // triggers StockReservationFailed -> compensation
        }
        // Semantic lock: move to RESERVED, not SOLD. Visible as unavailable to others.
        item.reserve(orderId, qty);
        stock.save(item); // @Version on StockItem throws on concurrent modification -> retry
        return true;
    }

    @Transactional
    public void releaseReservation(UUID orderId, String sku, int qty) {
        // Compensation C3 — idempotent: only release if a reservation exists.
        stock.findBySku(sku).ifPresent(item -> {
            if (item.hasReservation(orderId)) {
                item.release(orderId, qty);
                stock.save(item);
            }
        });
    }
}

Other countermeasures worth knowing: commutative updates (design operations so order does not matter — credit/debit instead of setBalance), pessimistic views (reorder steps so the riskiest comes first, shrinking the window of inconsistency), and re-reads / version checks before compensating to detect intervening changes. None of these gives you true isolation; they reduce the probability and blast radius of anomalies. You must decide, per saga, which anomalies your business can tolerate.

When to use the saga pattern — and when not to

Use a saga when:

• A business operation spans multiple services with separate databases and you need an all-or-nothing business outcome.
• The participants cannot or should not be coupled by 2PC (third-party APIs, message brokers, high-throughput hot rows).
• You can tolerate eventual consistency and brief windows where partial results are visible.

Do not reach for a saga when:

• The data belongs together. If three services are always changing in one transaction, that is a hint your service boundaries are wrong. The cheapest fix is often to merge them into one service with one database and one ordinary @Transactional — no saga needed.
• You need strong isolation / read-your-writes semantics for the in-flight operation. Sagas cannot give you serializability across services.
• The operation is genuinely single-service. Do not build a saga for something a local transaction handles.

Pitfalls checklist

• Dual-write without an outbox. Committing the DB then publishing as two separate operations will eventually drop or duplicate events. Always use a transactional outbox (or CDC) so the event and the state change share one transaction.
• Non-idempotent consumers and compensations. At-least-once delivery means everything runs more than once. Dedupe by event id; make compensations no-ops when already applied.
• Forgetting that compensations can fail. Retry them forever (with backoff) and alert; never silently drop.
• Ignoring isolation anomalies. Audit every saga for dirty reads and lost updates. Add semantic locks (status flags, reservations) deliberately, not by accident.
• Choreography sprawl. Beyond ~4 steps or any branching, the implicit event web becomes unmaintainable and prone to cyclic dependencies. Switch to orchestration.
• No saga timeout. A step’s reply may never come. Set per-step timeouts so a stuck saga triggers compensation instead of hanging forever.
• Treating retriable steps as compensatable. Do not unwind a customer’s whole order because a non-critical post-pivot step (email, analytics) failed. Retry it.

Closing thought

Sagas are not a free upgrade from 2PC — they are a different deal. You trade global atomicity-with-isolation for atomicity-without-isolation, and you pay for it in idempotency code, compensation logic, and careful anomaly analysis. Done well, they let independent services stay independent while still delivering coherent business outcomes. Done carelessly, they leave money charged against cancelled orders. The difference is entirely in how seriously you take the failure path.

If this breakdown helped, follow the devdomain publication for more deep dives into distributed systems and backend architecture. Have you run sagas in production — choreography or orchestration, and what bit you? Drop your war stories in the comments; the messy real-world cases are the best part.

The Saga Pattern: Managing Distributed Transactions Across MicroservicesYou split a monolith into… was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

A union (|) says a value is one of several types. A literal type narrows it to one exact value. Together they're TypeScript's superpower.

Literal types

Instead of string, accept only specific strings:

type Direction = "up" | "down" | "left" | "right";

function move(d: Direction) { /* ... */ }

move("up");   // ok
move("north"); // error: not a Direction

Narrowing

TypeScript narrows the type as you check it:

type Status = "loading" | "success" | "error";

function render(s: Status) {
  if (s === "error") {
    // s is "error" here
    return "Something broke";
  }
  return s; // s is "loading" | "success"
}

Combine with switch for exhaustive handling — every case covered, compiler-verified.

TL;DR: Unions + literals replace loose string/number with a precise set of allowed values.

Swap a stringly-typed parameter for a literal union and watch the bugs vanish.

Union & Literal Types 🔀 was originally published in The 60-Second Programmer on Medium, where people are continuing the conversation by highlighting and responding to this story.

Want to run something concurrently in Go? Put go in front of it. Done.

What is a goroutine?

A goroutine is a lightweight thread managed by the Go runtime. They start with a tiny stack (a few KB) and grow as needed, so you can spawn thousands without breaking a sweat. The scheduler multiplexes them onto OS threads for you.

Starting one

package main

import (
	"fmt"
	"sync"
)

func main() {
	var wg sync.WaitGroup
	for i := 0; i

Watch out

main returning kills every goroutine, so coordinate with sync.WaitGroup or a channel. Goroutines run independently. Use channels or mutexes to share data safely. Capture loop variables explicitly (pass i as an argument) unless you're on Go 1.22+.

TL;DR: go f() launches concurrent work; use WaitGroup or channels to wait for it.

Try spawning 1,000 goroutines and watch how fast they finish. 🐹

Goroutines Explained 🚀 was originally published in The 60-Second Programmer on Medium, where people are continuing the conversation by highlighting and responding to this story.

The fix is a single, consistent error contract enforced in one place. Spring Boot gives you the tools: @ControllerAdvice for centralized handling, @ExceptionHandler for mapping exceptions to responses, and — since Spring 6 / Boot 3 — first-class support for ProblemDetail, the standardized error format defined by RFC 7807 (now RFC 9457). This article builds a complete, production-grade error-handling layer.

The problem with scattered error handling

Without a strategy, error handling spreads across controllers:

// DON'T: error handling tangled into business code
@GetMapping("/orders/{id}")
public ResponseEntity<?> getOrder(@PathVariable Long id) {
    Order o = repo.findById(id).orElse(null);
    if (o == null) {
        return ResponseEntity.status(404)
            .body(Map.of("error", "order not found"));
    }
    return ResponseEntity.ok(o);
}

Every controller reinvents the wheel, formats differ, and cross-cutting concerns (logging, correlation IDs) get copy-pasted. Centralize instead: let controllers throw meaningful exceptions and translate them in one advice.

RFC 7807: a standard error shape

RFC 7807 (“Problem Details for HTTP APIs”) defines a media type, application/problem+json, and a canonical structure:

| Field | Meaning |
|---|---|
| `type` | A URI identifying the problem type (a stable, dereferenceable category) |
| `title` | A short, human-readable summary of the problem type |
| `status` | The HTTP status code |
| `detail` | A human-readable explanation specific to this occurrence |
| `instance` | A URI identifying this specific occurrence |

Plus any extension members you add (e.g. errors, traceId). A compliant response looks like:

{
  "type": "https://api.example.com/problems/order-not-found",
  "title": "Order Not Found",
  "status": 404,
  "detail": "No order exists with id 4711",
  "instance": "/orders/4711",
  "traceId": "0af7651916cd43dd8448eb211c80319c"
}

Spring 6 models this with the org.springframework.http.ProblemDetail class — no third-party library required.

ProblemDetail by hand

ProblemDetail is a plain holder you can build and return directly:

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import java.net.URI;

ProblemDetail pd = ProblemDetail.forStatusAndDetail(
    HttpStatus.NOT_FOUND, "No order exists with id 4711");
pd.setType(URI.create("https://api.example.com/problems/order-not-found"));
pd.setTitle("Order Not Found");
pd.setProperty("traceId", "0af7651916cd43dd8448eb211c80319c"); // extension member

setProperty adds arbitrary extension fields, serialized flat alongside the standard ones.

Turning it on for built-in exceptions

Spring MVC throws a family of internal exceptions (e.g. HttpMessageNotReadableException, MethodArgumentNotValidException, NoResourceFoundException). To make Spring render those as ProblemDetail automatically, enable the property:

spring.mvc.problemdetails.enabled=true

(WebFlux uses spring.webflux.problemdetails.enabled=true.) With this on, framework-level errors already come back as RFC 7807 documents. Your job is to handle your exceptions consistently and enrich the defaults.

Global handling with @RestControllerAdvice

@ControllerAdvice (or @RestControllerAdvice, which adds @ResponseBody) registers exception handlers that apply across all controllers. Combined with ProblemDetail returns, it's the backbone of a clean contract.

Define domain exceptions first:

public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) { super(message); }
}

public class BusinessRuleException extends RuntimeException {
    private final String code;
    public BusinessRuleException(String code, String message) {
        super(message);
        this.code = code;
    }
    public String getCode() { return code; }
}

Now the central advice:

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.net.URI;
import java.time.Instant;

@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
    private static final String BASE = "https://api.example.com/problems/";

    @ExceptionHandler(ResourceNotFoundException.class)
    public ProblemDetail handleNotFound(ResourceNotFoundException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setType(URI.create(BASE + "resource-not-found"));
        pd.setTitle("Resource Not Found");
        pd.setProperty("timestamp", Instant.now());
        return pd;
    }

    @ExceptionHandler(BusinessRuleException.class)
    public ProblemDetail handleBusinessRule(BusinessRuleException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
        pd.setType(URI.create(BASE + "business-rule-violation"));
        pd.setTitle("Business Rule Violation");
        pd.setProperty("code", ex.getCode());
        return pd;
    }

    // Catch-all: never leak stack traces to clients
    @ExceptionHandler(Exception.class)
    public ProblemDetail handleUnexpected(Exception ex) {
        log.error("Unhandled exception", ex); // log full detail server-side
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.INTERNAL_SERVER_ERROR,
            "An unexpected error occurred. Please contact support.");
        pd.setType(URI.create(BASE + "internal-error"));
        pd.setTitle("Internal Server Error");
        return pd;
    }
}

Two principles already baked in: never expose internal exception messages or stack traces to clients (the catch-all returns a generic detail while logging the real cause), and map each exception type to a meaningful status.

Handling validation errors properly

Bean Validation (jakarta.validation) is where consistent error responses pay off most, because clients need field-level detail to fix their input.

Annotate your request DTO:

import jakarta.validation.constraints.*;

public record CreateUserRequest(
    @NotBlank String username,
    @Email String email,
    @Min(18) int age,
    @Size(min = 8) String password
) {}

Trigger validation with @Valid:

@PostMapping("/users")
public ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest req) {
    // if invalid, MethodArgumentNotValidException is thrown before this runs
    return ResponseEntity.ok(service.create(req));
}

When validation fails, Spring throws MethodArgumentNotValidException. To emit a clean RFC 7807 response with per-field errors, extend ResponseEntityExceptionHandler — it already handles the Spring MVC exceptions and lets you customize them, returning ProblemDetail bodies:

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
import java.net.URI;
import java.util.ArrayList;
import java.util.List;

@RestControllerAdvice
public class ValidationExceptionHandler extends ResponseEntityExceptionHandler {

    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex,
            HttpHeaders headers,
            HttpStatusCode status,
            WebRequest request) {

        List<FieldError> errors = new ArrayList<>();
        ex.getBindingResult().getFieldErrors().forEach(fe ->
            errors.add(new FieldError(fe.getField(), fe.getDefaultMessage())));
        ex.getBindingResult().getGlobalErrors().forEach(ge ->
            errors.add(new FieldError(ge.getObjectName(), ge.getDefaultMessage())));

        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            org.springframework.http.HttpStatus.BAD_REQUEST,
            "Request validation failed");
        pd.setType(URI.create("https://api.example.com/problems/validation-error"));
        pd.setTitle("Validation Error");
        pd.setProperty("errors", errors);

        return ResponseEntity.badRequest().body(pd);
    }

    public record FieldError(String field, String message) {}
}

Resulting payload:

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    { "field": "email", "message": "must be a well-formed email address" },
    { "field": "age", "message": "must be greater than or equal to 18" }
  ]
}

Handling constraint violations on path/query params

@Valid on a body throws MethodArgumentNotValidException. But validating method parameters directly (e.g. @RequestParam @Min(1) int page with @Validated on the controller) throws jakarta.validation.ConstraintViolationException instead — a different exception. Handle it too:

import jakarta.validation.ConstraintViolationException;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ExceptionHandler(ConstraintViolationException.class)
public ProblemDetail handleConstraintViolation(ConstraintViolationException ex) {
    var errors = ex.getConstraintViolations().stream()
        .map(v -> new FieldError(v.getPropertyPath().toString(), v.getMessage()))
        .toList();
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(
        org.springframework.http.HttpStatus.BAD_REQUEST, "Constraint violation");
    pd.setProperty("errors", errors);
    return pd;
}

ErrorResponseException and ProblemDetail-aware exceptions

Spring 6 introduced ErrorResponse and ErrorResponseException, which carry their own ProblemDetail. You can make domain exceptions self-describing by implementing ErrorResponse, so they render correctly even without a dedicated handler:

import org.springframework.http.HttpStatus;
import org.springframework.web.ErrorResponseException;
import org.springframework.http.ProblemDetail;
import java.net.URI;

public class OrderNotFoundException extends ErrorResponseException {
    public OrderNotFoundException(Long id) {
        super(HttpStatus.NOT_FOUND, problem(id), null);
    }
    private static ProblemDetail problem(Long id) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, "No order exists with id " + id);
        pd.setType(URI.create("https://api.example.com/problems/order-not-found"));
        pd.setTitle("Order Not Found");
        return pd;
    }
}

Throwing this from a controller produces a correct application/problem+json response with no handler at all — Spring recognizes ErrorResponse and renders it.

Enriching every response: instance URI and trace IDs

Clients and support teams need to correlate an error to a log line. Add the request path as instance and a trace ID as an extension. A small helper on the advice keeps it DRY:

import org.springframework.web.context.request.ServletWebRequest;
import org.springframework.web.context.request.WebRequest;
import java.net.URI;

private void enrich(ProblemDetail pd, WebRequest request) {
    if (request instanceof ServletWebRequest swr) {
        pd.setInstance(URI.create(swr.getRequest().getRequestURI()));
    }
    // From MDC / tracing context (e.g. Micrometer Tracing populates this)
    String traceId = org.slf4j.MDC.get("traceId");
    if (traceId != null) pd.setProperty("traceId", traceId);
}

Call enrich(pd, request) at the end of each handler (add WebRequest request to the handler signatures). Now every error is traceable.

Scoping advice and ordering multiple handlers

@RestControllerAdvice applies globally by default, but you can scope it — useful in modular applications where different packages need different error contracts (e.g. a public API vs an internal admin API):

// Only applies to controllers in the public API package
@RestControllerAdvice(basePackages = "com.example.api.public_")
public class PublicApiExceptionHandler { ... }

// Only applies to controllers annotated with @AdminApi
@RestControllerAdvice(annotations = AdminApi.class)
public class AdminApiExceptionHandler { ... }

When more than one advice can handle the same exception type, Spring resolves by @Order (lower value wins) and by handler specificity — a handler for ResourceNotFoundException beats one for RuntimeException. Keep this predictable: prefer a single advice per concern, and only layer them when you have a genuine reason (a fallback advice with @Order(Ordered.LOWEST_PRECEDENCE) catching Exception is a common, legitimate pattern).

How handler method resolution works

When an exception escapes a controller, Spring’s ExceptionHandlerExceptionResolver walks the advice beans and looks for the most specific @ExceptionHandler whose declared types match the thrown exception (or a cause, when configured). Matching considers the exception hierarchy, so a handler for a superclass catches subclasses unless a more specific handler exists. This is why a catch-all @ExceptionHandler(Exception.class) reliably acts as a backstop: it matches everything, but loses to any narrower handler.

exception thrown in controller
        |
        v
ExceptionHandlerExceptionResolver
        |
        v
find most specific @ExceptionHandler across @ControllerAdvice beans
        |
        +-- match found  -> invoke handler -> render ProblemDetail
        |
        +-- no match     -> propagate to container -> default error page / 500

Content negotiation and the problem+json media type

When you return a ProblemDetail, Spring serializes it as application/problem+json (for JSON) or application/problem+xml (for XML), per the RFC. Clients that inspect the Content-Type can branch on it to detect an error envelope without parsing the body first. This is one of the quiet advantages of the standard: the media type itself signals "this is a problem document," which generic HTTP clients and gateways can act on.

If you instead return a hand-rolled Map or custom DTO, you lose that signal and the standard structure, and every consumer must special-case your shape. Returning ProblemDetail is therefore not just cleaner code — it's a more interoperable contract.

Testing your error contract

Error handling is exactly the kind of code that rots silently, so test it. A @WebMvcTest slice exercises the advice without booting the full context:

import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.web.servlet.MockMvc;
import org.junit.jupiter.api.Test;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(OrderController.class)
class OrderErrorContractTest {

    @Autowired MockMvc mvc;

    @Test
    void missingOrder_returnsProblemDetail() throws Exception {
        mvc.perform(get("/orders/4711"))
           .andExpect(status().isNotFound())
           .andExpect(content().contentType("application/problem+json"))
           .andExpect(jsonPath("$.title").value("Order Not Found"))
           .andExpect(jsonPath("$.status").value(404))
           .andExpect(jsonPath("$.type").exists());
    }
}

Asserting on Content-Type and the standard fields locks down the contract so a future refactor can't quietly change the error shape your clients depend on.

A summary of the mapping strategy

| Exception | HTTP status | Where handled |
|---|---|---|
| `ResourceNotFoundException` (yours) | 404 | `@ExceptionHandler` |
| `BusinessRuleException` (yours) | 422 | `@ExceptionHandler` |
| `MethodArgumentNotValidException` | 400 | Override in `ResponseEntityExceptionHandler` |
| `ConstraintViolationException` | 400 | `@ExceptionHandler` |
| `HttpMessageNotReadableException` | 400 | Built-in (problemdetails enabled) |
| `AccessDeniedException` | 403 | Security layer / advice |
| Anything else | 500 | Catch-all `@ExceptionHandler(Exception.class)` |

Common pitfalls

• Leaking internals: returning ex.getMessage() from a generic 500 can expose SQL, file paths, or class names. The catch-all must return a generic message and log the real cause.
• Two handlers for the same exception: if both a plain @RestControllerAdvice and a ResponseEntityExceptionHandler subclass handle the same type, ordering is ambiguous. Keep one source of truth; use @Order on advices if you must layer them.
• Forgetting @Valid: validation annotations on a DTO do nothing without @Valid (body) or @Validated (params) at the call site.
• Confusing the two validation exceptions: body validation throws MethodArgumentNotValidException; param validation throws ConstraintViolationException. Handle both.
• Not enabling spring.mvc.problemdetails.enabled: without it, built-in framework errors won't be RFC 7807 by default.
• Returning the wrong status for business errors: 422 (Unprocessable Entity) often fits domain-rule failures better than 400 (malformed request). Choose intentionally.
• Self-invocation / exceptions thrown outside the dispatcher: @ControllerAdvice only catches exceptions propagating out of controller handling. Errors in filters or async threads need separate handling.
• Inconsistent type URIs: keep them stable and documented; clients may branch on type, so changing it is a breaking change.

Best practices

• One @RestControllerAdvice per concern (e.g. domain errors, validation), each focused and small.
• Use ProblemDetail everywhere so the contract is uniform and standards-compliant (application/problem+json).
• Make type URIs stable and resolvable to documentation; treat them as part of your API contract.
• Always include instance and a traceId for correlation.
• Map exceptions to semantic status codes; never default everything to 400 or 500.
• Validate at the edge with Bean Validation and surface field-level errors as an errors extension array.
• Log full detail server-side; return only safe, actionable detail to clients.
• Cover the catch-all so an unexpected exception never escapes as a stack trace.

Conclusion

Consistent error handling is a contract, not an afterthought. Spring Boot 3 makes that contract cheap to honor: @RestControllerAdvice centralizes mapping, @ExceptionHandler ties exceptions to responses, and built-in ProblemDetail gives you RFC 7807 / 9457 compliance without a library. Enable spring.mvc.problemdetails.enabled, extend ResponseEntityExceptionHandler for validation, enrich every response with an instance URI and traceId, and guard against leaks with a generic catch-all. The result is an API where every error — from a missing resource to an invalid field to a catastrophic 500 — speaks the same predictable language.

If this helped you standardize your API’s errors, follow devdomain for more Spring Boot deep dives, and drop a comment with the ugliest error payload you’ve had to consume. Misery loves company.

Spring Boot Error Handling: @ControllerAdvice and ProblemDetail (RFC 7807)Most APIs leak. was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

An LLM (Large Language Model) is a neural network trained on huge amounts of text to predict the next token. That’s it. Everything else — answering questions, writing code, summarizing — emerges from doing that one thing extremely well.

How it works

Your text is split into tokens (roughly word-fragments). The model assigns a probability to every possible next token, picks one, appends it, and repeats. A paragraph is just the model running that prediction step hundreds of times.

"The capital of France is" → [Paris: 0.92] [Lyon: 0.01] ... → "Paris"

What it is NOT

Not a database — it doesn’t “look up” facts; it predicts plausible text, so it can be wrong (a “hallucination”). Not deterministic by default — sampling makes outputs vary between runs. Not stateful — each request is independent. You resend the full conversation every time.

Calling one

import anthropic

client = anthropic.Anthropic()
resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain an LLM in one sentence."}],
)
print(resp.content[0].text)

TL;DR: An LLM is a next-token predictor trained at scale — powerful, but it generates plausible text, not verified truth.

Try one against a real prompt before you trust it for anything that matters. →

LLMs Explained 🧠 was originally published in The 60-Second Programmer on Medium, where people are continuing the conversation by highlighting and responding to this story.

Then the file grows to 12 million rows. The loop runs out of heap. A network blip on row 8,000,000 kills the process — and you have no idea which rows committed, so you can’t safely re-run it. There’s no progress reporting, no retry, no parallelism, and certainly no way to resume from where it died.

This is exactly the problem Spring Batch was built to solve. It provides a battle-tested framework for chunk-oriented processing with transactions, restartability, skip/retry policies, and partitioned parallelism — the unglamorous machinery that turns a fragile script into a reliable production job. This article builds a complete, real example and covers the production concerns that matter.

The core model

Spring Batch organizes work into a hierarchy:

• A Job is the whole unit of work (e.g. "import customers").
• A Job has one or more Steps, run in sequence (or conditionally).
• A chunk-oriented Step is built from three collaborators:
• ItemReader — reads one item at a time from a source (file, DB, queue).
• ItemProcessor — transforms/validates/filters one item (optional).
• ItemWriter — writes items in batches (a chunk) to a destination.
• The JobRepository persists execution metadata to the database, which is what makes restart and monitoring possible.
• A JobLauncher starts a job with a set of JobParameters.

The key insight is chunk-oriented processing: read N items one by one, process each, then hand the whole chunk of N to the writer inside a single transaction. Commit, repeat. This bounds memory to one chunk and gives you natural transactional boundaries.

Project setup

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-batch</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

Spring Batch needs its metadata tables (BATCH_JOB_INSTANCE, BATCH_STEP_EXECUTION, etc.). Spring Boot creates them automatically:

spring.batch.jdbc.initialize-schema=always
# Don't run jobs automatically on context startup; we'll launch explicitly
spring.batch.job.enabled=false

In Spring Boot 3 / Spring Batch 5, @EnableBatchProcessing is no longer required — auto-configuration wires the JobRepository, JobLauncher, and a JDBC transactionManager for you. (Adding @EnableBatchProcessing actually disables that auto-config, so leave it off unless you need to customize.)

A complete worked example

The job: read a large CSV of raw customer records, validate and normalize them, and persist valid ones to the database.

The domain

public record CustomerCsv(String firstName, String lastName, String email, String country) {}

@Entity
@Table(name = "customer")
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String firstName;
    private String lastName;
    private String email;
    private String countryCode;
    // getters / setters
}

The reader

FlatFileItemReader streams the file line by line — it never loads the whole file into memory.

import org.springframework.batch.item.file.FlatFileItemReader;
import org.springframework.batch.item.file.builder.FlatFileItemReaderBuilder;
import org.springframework.core.io.FileSystemResource;

@Bean
@StepScope
public FlatFileItemReader<CustomerCsv> customerReader(
        @Value("#{jobParameters['inputFile']}") String inputFile) {
    return new FlatFileItemReaderBuilder<CustomerCsv>()
        .name("customerReader")
        .resource(new FileSystemResource(inputFile))
        .linesToSkip(1)                       // header row
        .delimited()
        .names("firstName", "lastName", "email", "country")
        .targetType(CustomerCsv.class)
        .build();
}

@StepScope is important: it lets the reader receive a late-bound jobParameters value (the file path) and gives each execution its own reader instance.

The processor

The processor validates and normalizes. Returning null from a processor filters the item — it is silently dropped and never reaches the writer.

import org.springframework.batch.item.ItemProcessor;
import org.springframework.stereotype.Component;

@Component
public class CustomerProcessor implements ItemProcessor<CustomerCsv, Customer> {

    private static final java.util.regex.Pattern EMAIL =
        java.util.regex.Pattern.compile("^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$");

    @Override
    public Customer process(CustomerCsv in) {
        if (in.email() == null || !EMAIL.matcher(in.email().trim()).matches()) {
            return null; // filter out invalid rows
        }
        Customer c = new Customer();
        c.setFirstName(in.firstName().trim());
        c.setLastName(in.lastName().trim());
        c.setEmail(in.email().trim().toLowerCase());
        c.setCountryCode(normalizeCountry(in.country()));
        return c;
    }

    private String normalizeCountry(String raw) {
        if (raw == null) return "XX";
        return raw.trim().toUpperCase().substring(0, Math.min(2, raw.trim().length()));
    }
}

The writer

JpaItemWriter persists a whole chunk in one transaction.

import org.springframework.batch.item.data.JpaItemWriter;
import org.springframework.batch.item.data.builder.JpaItemWriterBuilder;
import jakarta.persistence.EntityManagerFactory;

@Bean
public JpaItemWriter<Customer> customerWriter(EntityManagerFactory emf) {
    return new JpaItemWriterBuilder<Customer>()
        .entityManagerFactory(emf)
        .build();
}

For Raw throughput, JdbcBatchItemWriter with a parameterized INSERT is faster because it bypasses the persistence context:

@Bean
public JdbcBatchItemWriter<Customer> jdbcCustomerWriter(DataSource dataSource) {
    return new JdbcBatchItemWriterBuilder<Customer>()
        .dataSource(dataSource)
        .sql("""
            insert into customer (first_name, last_name, email, country_code)
            values (:firstName, :lastName, :email, :countryCode)
            """)
        .beanMapped()
        .build();
}

Wiring the Step and Job

In Spring Batch 5 you build steps and jobs with builders that take the JobRepository and a transaction manager.

import org.springframework.batch.core.Job;
import org.springframework.batch.core.Step;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class CustomerImportJobConfig {

    @Bean
    public Step importStep(JobRepository jobRepository,
                           PlatformTransactionManager txManager,
                           FlatFileItemReader<CustomerCsv> customerReader,
                           CustomerProcessor processor,
                           JpaItemWriter<Customer> customerWriter) {
        return new StepBuilder("importStep", jobRepository)
            .<CustomerCsv, Customer>chunk(1000, txManager)
            .reader(customerReader)
            .processor(processor)
            .writer(customerWriter)
            .build();
    }

    @Bean
    public Job importCustomersJob(JobRepository jobRepository, Step importStep) {
        return new JobBuilder("importCustomersJob", jobRepository)
            .start(importStep)
            .build();
    }
}

chunk(1000, txManager) means: read up to 1,000 items, process them, write all 1,000, and commit — then start the next chunk. Pick a chunk size that balances transaction overhead against memory and lock duration. 500–2,000 is a sensible starting range; benchmark for your workload.

Launching the job

import org.springframework.batch.core.*;
import org.springframework.batch.core.launch.JobLauncher;

@Component
public class CustomerImportRunner {

    private final JobLauncher jobLauncher;
    private final Job importCustomersJob;

    public CustomerImportRunner(JobLauncher jobLauncher, Job importCustomersJob) {
        this.jobLauncher = jobLauncher;
        this.importCustomersJob = importCustomersJob;
    }

    public void run(String inputFile) throws Exception {
        JobParameters params = new JobParametersBuilder()
            .addString("inputFile", inputFile)
            .addLong("run.timestamp", System.currentTimeMillis()) // makes the instance unique
            .toJobParameters();
        jobLauncher.run(importCustomersJob, params);
    }
}

Restartability

This is Spring Batch’s superpower. Because the JobRepository persists step execution state — including the read count — a job that failed can be re-launched with the same identifying job parameters and it resumes from the last committed chunk rather than starting over.

A few rules govern this:

• A JobInstance is identified by job name + identifying job parameters. Re-running with the same identifying parameters continues that instance; changing them creates a new instance.
• That’s why above we add a run.timestamp — a unique parameter makes each launch a fresh instance. For a restartable job you'd instead keep parameters identical (e.g. just inputFile) so a failed run can resume.
• A COMPLEQED instance cannot be re-run with the same parameters (you'd get JobInstanceAlreadyCompleteException). Only FAILED/STOPPED instances restart.
• Readers like FlatFileItemReader are restartable: they persist the line offset in the ExecutionContext and skip already-read lines on restart.

You can also mark a step non-restartable or allow a completed step to re-run with .allowStartIfComplete(true).

Fault tolerance: skip and retry

In the real world some records are simply bad and some failures are transient. A fault-tolerant step lets you handle both without aborting the whole job.

@Bean
public Step faultTolerantStep(JobRepository jobRepository,
                              PlatformTransactionManager txManager,
                              FlatFileItemReader<CustomerCsv> reader,
                              CustomerProcessor processor,
                              JpaItemWriter<Customer> writer) {
    return new StepBuilder("faultTolerantStep", jobRepository)
        .<CustomerCsv, Customer>chunk(1000, txManager)
        .reader(reader)
        .processor(processor)
        .writer(writer)
        .faultTolerant()
        // retry transient failures up to 3 times
        .retryLimit(3)
        .retry(org.springframework.dao.TransientDataAccessException.class)
        // skip bad records, up to 50 of them, then fail the job
        .skipLimit(50)
        .skip(org.springframework.batch.item.file.FlatFileParseException.class)
        .skip(jakarta.validation.ConstraintViolationException.class)
        .listener(skipListener())
        .build();
}

• Retry re-attempts an operation that threw a transient exception (a deadlock, a momentary connection drop). Use it only for errors that might succeed on a second try.
• Skip discards an individual bad item (a malformed CSV line, a validation failure) and continues, up to skipLimit. Exceed the limit and the job fails — that's a safety valve against silently dropping a corrupt file.
• Capture skips so they aren’t lost:

@Bean
public org.springframework.batch.core.SkipListener<CustomerCsv, Customer> skipListener() {
    return new org.springframework.batch.core.SkipListener<>() {
        @Override
        public void onSkipInRead(Throwable t) {
            // log/persist the unparseable line for later inspection
        }
        @Override
        public void onSkipInProcess(CustomerCsv item, Throwable t) {
            // record rejected item to a dead-letter table
        }
        @Override
        public void onSkipInWrite(Customer item, Throwable t) {
            // record write failure
        }
    };
}

Important caveat: when a fault-tolerant chunk hits an error during write, Spring Batch rolls back the chunk and re-processes it item by item to isolate the offender. This means your ItemProcessor must be idempotent — it may be called more than once for the same item.

Partitioning for scale

A single thread reading and writing in chunks is reliable but sequential. For millions of rows you want parallelism. Partitioning splits the input into ranges and runs a separate worker step per partition, each with its own reader/writer, in parallel across a thread pool.

import org.springframework.batch.core.partition.support.Partitioner;
import org.springframework.batch.item.ExecutionContext;
import java.util.HashMap;
import java.util.Map;

public class IdRangePartitioner implements Partitioner {

    private final long minId;
    private final long maxId;

    public IdRangePartitioner(long minId, long maxId) {
        this.minId = minId;
        this.maxId = maxId;
    }

    @Override
    public Map<String, ExecutionContext> partition(int gridSize) {
        Map<String, ExecutionContext> partitions = new HashMap<>();
        long range = (maxId - minId) / gridSize + 1;
        long start = minId;
        for (int i = 0; i < gridSize; i++) {
            ExecutionContext ctx = new ExecutionContext();
            long end = Math.min(start + range - 1, maxId);
            ctx.putLong("minId", start);
            ctx.putLong("maxId", end);
            partitions.put("partition" + i, ctx);
            start = end + 1;
        }
        return partitions;
    }
}

Wire a manager step that distributes partitions to a worker step running on a task executor:

@Bean
public Step partitionedStep(JobRepository jobRepository,
                            Step workerStep) {
    return new StepBuilder("partitionedStep", jobRepository)
        .partitioner(workerStep.getName(),
                     new IdRangePartitioner(1, 12_000_000))
        .step(workerStep)
        .gridSize(8)
        .taskExecutor(new org.springframework.core.task.SimpleAsyncTaskExecutor())
        .build();
}

The worker step’s reader uses the partition’s minId/maxId from the step ExecutionContext (inject via @Value("#{stepExecutionContext['minId']}") on a @StepScope bean). For a DB source, a JdbcPagingItemReader with a where id between :minId and :maxId clause keeps each partition's reads bounded and indexed.

Spring Batch also supports remote partitioning (workers on separate JVMs, coordinated via a message queue) for horizontal scale beyond one machine. Local partitioning across threads is the simplest big win.

Listeners and the ExecutionContext

Real jobs need hooks for logging, metrics, cleanup, and passing data between steps. Spring Batch provides listeners at every level.

import org.springframework.batch.core.JobExecution;
import org.springframework.batch.core.JobExecutionListener;

public class ImportJobListener implements JobExecutionListener {

    @Override
    public void beforeJob(JobExecution jobExecution) {
        // record start time, validate inputs, send a "started" notification
    }

    @Override
    public void afterJob(JobExecution jobExecution) {
        long written = jobExecution.getStepExecutions().stream()
            .mapToLong(se -> se.getWriteCount()).sum();
        long skipped = jobExecution.getStepExecutions().stream()
            .mapToLong(se -> se.getSkipCount()).sum();
        // emit metrics, alert if skipped is high, archive the input file
    }
}

Attach it with .listener(new ImportJobListener()) on the JobBuilder. There are matching StepExecutionListener, ChunkListener, and ItemReadListener interfaces for finer-grained hooks.

To pass data between steps — say, a step that computes an ID range and a later step that consumes it — write to the job ExecutionContext (shared across the job), not the step context (scoped to one step). The execution context is persisted by the JobRepository, so its contents also survive a restart, which is exactly what makes resumable multi-step jobs possible.

Composing multiple steps

Jobs rarely have one step. You might stage raw data, validate it, then load it. The JobBuilder flow API sequences and branches steps:

@Bean
public Job pipelineJob(JobRepository repo, Step stageStep,
                       Step validateStep, Step loadStep, Step cleanupStep) {
    return new JobBuilder("pipelineJob", repo)
        .start(stageStep)
        .next(validateStep)
        .on("FAILED").to(cleanupStep)          // branch on exit status
        .from(validateStep).on("*").to(loadStep)
        .end()
        .build();
}

If a step fails, the persisted state lets you restart the whole job and it resumes at the failed step — completed steps are skipped (unless marked allowStartIfComplete). This makes long ETL pipelines robust: a failure in the load step doesn't force you to re-stage gigabytes of data.

Tuning and monitoring

| Lever | Effect | Guidance |
|-------|--------|----------|
| Chunk size | Transaction frequency vs memory | Start 500–2,000; benchmark |
| Partition grid size | Parallelism | Match to CPU cores / DB connection pool |
| `JdbcBatchItemWriter` | Throughput | Faster than JPA for pure inserts |
| Connection pool size | Concurrency ceiling | Pool ≥ grid size + headroom |
| `default_batch_fetch_size` | Reader efficiency | Reduce N+1 if reader touches associations |

Monitor via the BATCH_STEP_EXECUTION table (read/write/skip/commit counts) or expose Micrometer metrics — Spring Batch publishes spring.batch.job and spring.batch.step timers automatically when Actuator is present.

Common pitfalls

• Loading everything into memory. Use streaming readers (FlatFileItemReader, JdbcCursorItemReader, JdbcPagingItemReader), never findAll() into a List.
• Non-idempotent processors. Fault-tolerant retries re-invoke process(). Side effects must be safe to repeat.
• Reusing identifying job parameters on a completed job. Causes JobInstanceAlreadyCompleteException. Add a unique parameter for genuinely new runs; keep them identical only when you intend to restart.
• Skipping silently. A high skipLimit with no SkipListener quietly discards data. Always record skipped items to a dead-letter store and alert on volume.
• Huge chunk inside a single transaction. A 100,000-item chunk holds locks and a giant transaction; a failure rolls back everything. Keep chunks modest.
• @EnableBatchProcessing in Boot 3. It disables the auto-configuration you actually want. Omit it unless customizing.
• spring.batch.job.enabled=true running jobs on every startup. Disable auto-run and launch explicitly so you control parameters and timing.
• Partitioning without enough DB connections. Eight parallel workers need eight connections; size the pool accordingly or workers will block.

Wrapping up

Spring Batch is not the flashiest part of the Spring ecosystem, but it’s one of the most valuable. It turns “read a file and insert rows” into a job that streams within bounded memory, commits in transactional chunks, resumes after failure, skips bad records into a dead-letter store, retries transient errors, and scales out across partitions.

Build with ItemReader → ItemProcessor → ItemWriter, choose a sane chunk size, make your processor idempotent, add fault tolerance deliberately, and partition when you need throughput. Your 12-million-row import becomes boring — which, for a batch job, is exactly what you want.

If this leveled up your batch game, follow the devdomain publication for more deep Spring engineering. What’s the largest job you’ve run, and how did you tune it? Share your numbers in the comments.

Spring Batch: Processing Millions of Records ReliablyIt always starts simple. was originally published in devdomain on Medium, where people are continuing the conversation by highlighting and responding to this story.

Both are relative font-size units, but they measure against different things — and that difference matters.

em → relative to the parent

1em equals the parent element's font size. So em values compound as you nest.

.parent { font-size: 20px; }
.child  { font-size: 1.5em; } /* 30px */
.grandchild { font-size: 1.5em; } /* 45px — compounds! */

That cascading can surprise you when components nest deeply.

rem → relative to the root

1rem always equals the root (<html>) font size, no matter how deep you are. No compounding.

html { font-size: 16px; }
.title { font-size: 2rem;  } /* always 32px */
.body  { font-size: 1rem;  } /* always 16px */

When to use which

rem for font sizes and most layout — predictable and accessibility-friendly (it respects the user's browser font setting). em for spacing that should scale with its own text, like button padding:

.btn {
  font-size: 1.25rem;
  padding: 0.5em 1em; /* scales with the button's text */
}

TL;DR: Use rem for consistent, accessible sizing; reach for em when you want a value to scale with its local font size.

Set padding in em on a button, then bump its font-size — the padding scales right along with it.

em vs rem Explained 📏 was originally published in The 60-Second Programmer on Medium, where people are continuing the conversation by highlighting and responding to this story.