Ch. 8 · Spring Boot

Spring JPA Optimistic Locking and Conflicts

How JPA @Version prevents lost updates in Spring Boot, what ObjectOptimisticLockingFailureException means, and when to retry or return 409.

~7 min readintermediateupdated Nov 1, 2026

Two users edit the same record at the same time, and the second save silently overwrites the first. This is the lost update problem. In a Spring Boot service running several instances, Java locks such as synchronized cannot help, because each instance has its own memory and the database is the only shared place. JPA optimistic locking with @Version detects the conflict in the database; the harder design question is what to do once a conflict happens. The examples use Spring Boot 3.x with Hibernate 6 and rely on dirty checking, which issues the UPDATE at flush time.

@Version in one paragraph, and what to do on a conflict

Add a @Version field (usually long) to the entity. Hibernate includes the version in every UPDATE ... WHERE id = ? AND version = ? and increments it. If another transaction changed the row first, the update matches zero rows and Hibernate throws OptimisticLockException, which Spring translates into ObjectOptimisticLockingFailureException. No database lock is held between read and write, so it suits low-contention data. For user edits, return 409 Conflict and let the user reload; for idempotent background updates, retry the whole transaction. For an API, the client must send back the version it read, or the protection only covers the milliseconds inside one request.

The WHERE version = ? clause that detects a lost update

@Entity
public class Product {
    @Id @GeneratedValue private Long id;
    private String name;
    private BigDecimal price;
    private int stock;

    @Version
    private long version;
    // getters and setters
}
java

Load product 7 (version 3), change the price, commit. Hibernate issues this statement (the id and version bind values are shown inline for readability):

update product set name=?, price=?, stock=?, version=4 where id=7 and version=3
sql

The JDBC driver reports the update count. If it is 1, the write succeeded and the entity now has version 4. If it is 0, someone else already moved the row to version 4, and Hibernate throws. The check is atomic because the database evaluates the WHERE clause and the write together.

Here is the timeline that optimistic locking prevents:

T1: read product 7 (price 10, version 3)
T2: read product 7 (price 10, version 3)
T2: set price 12  -> update ... where version=3  -> 1 row, version 4
T1: set price 11  -> update ... where version=3  -> 0 rows -> OptimisticLockException
Text

Without @Version, T1’s update would silently overwrite T2’s price.

From a version column to 409s and safe retries

Step 1: Add the version column

Add @Version private long version; and a database migration with version bigint not null default 0. Do not write setters that let application code change it. Hibernate owns it.

Step 2: Carry the version through the API

A web edit spans two requests: GET to show the form, PUT to save. If the PUT handler loads a fresh entity and applies changes, it gets the current version, so the check passes even when the user edited stale data. The client must send the version it saw:

public record UpdatePriceRequest(@NotNull BigDecimal price, long version) { }

@Transactional
public Product updatePrice(long id, UpdatePriceRequest req) {
    Product product = products.findById(id).orElseThrow(() -> new ProductNotFoundException(id));
    if (product.getVersion() != req.version()) {
        throw new ObjectOptimisticLockingFailureException(Product.class, id);
    }
    product.setPrice(req.price());
    return product;   // flushed at commit with "where version = ?"
}
java

The explicit comparison catches staleness across requests; the WHERE version = ? at commit catches races within the request window. HTTP’s ETag and If-Match headers are the standard way to carry the version: return ETag: "3" on GET, require If-Match: "3" on PUT, and answer 412 Precondition Failed on mismatch.

Step 3: Map the conflict to a response

@ExceptionHandler(ObjectOptimisticLockingFailureException.class)
ProblemDetail conflict(ObjectOptimisticLockingFailureException ex) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT,
            "This record was changed by someone else. Reload and try again.");
    pd.setType(URI.create("https://api.example.com/problems/edit-conflict"));
    return pd;
}
java

Step 4: Retry only where retrying is correct

A background job that decrements stock can safely re-read and retry, because the decision (“is stock > 0?”) is recomputed from fresh data. The retry must wrap the whole transaction, not live inside it:

@Service
class StockService {
    private final StockTx tx;   // separate bean so @Transactional applies per attempt

    StockService(StockTx tx) { this.tx = tx; }

    @Retryable(retryFor = ObjectOptimisticLockingFailureException.class, maxAttempts = 3,
               backoff = @Backoff(delay = 50, multiplier = 2, random = true))
    public void reserve(long productId, int qty) {
        tx.reserve(productId, qty);
    }
}
java

@Retryable comes from Spring Retry (enable with @EnableRetry). Retrying inside the failed transaction does not work: the persistence context holds the stale entity, and the transaction is already marked rollback-only.

Two support agents and a credit limit that vanished

Picture a back-office tool that lets two support agents edit a customer’s shipping address and credit limit. Agent A opens the customer at 10:00 and changes the address. Agent B opens it at 10:01 and raises the credit limit, saving at 10:02. Agent A saves at 10:05. The PUT endpoint maps the whole form onto a freshly loaded entity, so A’s save writes the old credit limit back. B’s change is gone and nobody is told.

The entity already had @Version, which is what confused the team. But A’s request loaded the entity at 10:05, after B’s commit, so the version matched. The fix sends the version with the form, compares it as in Step 2, and returns 409 with a message. The UI then shows A the current values and asks them to reapply the address change. For field-level merging, the team could compare which fields A actually changed, but the simpler 409 resolves the data loss.

Where optimistic locking gets misapplied

  • “@Version alone protects the API.” It does only if the version the client read reaches the update. Loading fresh data in the PUT handler defeats it.
  • “Optimistic locking locks the row.” It holds no lock; it detects conflicts at write time.
  • Retrying user edits automatically. The retry reapplies the user’s change over someone else’s without their knowledge, which is the lost update again.
  • Catching the exception inside the @Transactional method. The exception surfaces at flush, often at commit after your method returns, and the transaction is already doomed.
  • Using optimistic locking for hot rows. A counter updated by hundreds of requests per second will conflict constantly; use an atomic SQL update (set stock = stock - ? where stock >= ?) or pessimistic locking instead.

Reproducing a stale update in a test

Simulate two transactions with TransactionTemplate:

@SpringBootTest
class ProductVersionTest {

    @Autowired ProductRepository products;
    @Autowired PlatformTransactionManager txManager;

    @Test
    void staleUpdateFails() {
        TransactionTemplate tx = new TransactionTemplate(txManager);
        long id = tx.execute(s -> products.save(new Product("Lamp", new BigDecimal("10"))).getId());

        Product stale = tx.execute(s -> products.findById(id).orElseThrow());   // version 0, detached

        tx.executeWithoutResult(s -> products.findById(id).orElseThrow().setPrice(new BigDecimal("12")));

        stale.setPrice(new BigDecimal("11"));
        assertThatThrownBy(() -> tx.executeWithoutResult(s -> products.save(stale)))
                .isInstanceOf(ObjectOptimisticLockingFailureException.class);
    }
}
java

save on the detached entity calls merge, which sees version 0 while the row is at version 1 and fails. The test does not use @Transactional on the class because it needs several independent commits.

Pessimistic locks, forced increments and bulk updates

When would you choose pessimistic locking? Choose it when conflicts are frequent or redoing the work is expensive, and keep the locked transaction short. @Lock(LockModeType.PESSIMISTIC_WRITE) on a repository method issues SELECT ... FOR UPDATE and holds a row lock until commit.

Can you force a version increment without changing fields? Yes, with LockModeType.OPTIMISTIC_FORCE_INCREMENT. It is useful when adding or changing child rows should conflict with concurrent edits to the parent aggregate.

What types can @Version use? JPA allows int, Integer, short, Short, long, Long and java.sql.Timestamp, and Hibernate also accepts newer date-time types such as Instant. Numbers are preferred because two writes within the timestamp’s precision can get the same value.

Does @Version work with bulk JPQL updates? No. update Product p set ... bypasses entity versioning unless you increment the version in the statement yourself.

An interview question to try: a flash sale on the last 50 units

In a flash sale, 1,000 users try to buy the last 50 units of a product in a few seconds. The product entity has @Version. What happens, and what would you change?

The answer, and the reasoning behind it

Most purchase transactions read the same version, so only one per version succeeds and the rest throw conflicts. Retries pile up, latency climbs, and many users fail even while stock remains. Optimistic locking is the wrong tool for a hot row. Use a single atomic statement, update product set stock = stock - 1 where id = ? and stock > 0, and check that the update count is 1. It serializes briefly inside the database with no lost updates and no retries. Alternatively, reserve stock through a queue or pre-split inventory into buckets. Keep @Version for ordinary product edits by staff, where conflicts are rare. The reasoning: choose the concurrency control by contention level.

Further reading on JPA and transactions

More in Spring Boot

esc