Home › Java exceptions › DataIntegrityViolationException

What it looks like

org.springframework.dao.DataIntegrityViolationException: could not execute statement [Duplicate entry ...] [insert into users ...]

Extends NonTransientDataAccessException in org.springframework.dao.

What it means

Spring Data and JdbcTemplate catch vendor-specific SQL exceptions and rethrow them as members of Spring's DataAccessException hierarchy, so that service code does not depend on the database. DataIntegrityViolationException is the umbrella for constraint violations. Under it sits DuplicateKeyException for unique key collisions. The original SQLException, with the vendor message naming the constraint, is the root cause at the bottom of the trace.

Common causes

• A unique constraint hit by a duplicate insert or update.
• A foreign key violation when saving a child whose parent is missing or deleting a parent that is referenced.
• A NOT NULL or CHECK constraint failing, or a value too long for the column ("Data too long for column").
• Concurrent transactions inserting the same natural key.

How to fix it

1. Scroll to the root cause and read the constraint name and column.
2. Catch DataIntegrityViolationException at the service boundary and translate it into a domain error or an HTTP 409 Conflict.
3. Validate lengths and nulls with Bean Validation before they reach the database.
4. Make operations idempotent (upsert, unique request ids) where retries can repeat an insert.

Broken and fixed

@PostMapping
public User create(@RequestBody User u) {
    return repo.save(u); // duplicate email -> 500

@ExceptionHandler(DataIntegrityViolationException.class)
ResponseEntity<String> conflict(DataIntegrityViolationException e) {
    return ResponseEntity.status(409).body("Already exists");
}

🔎 Unravel the failing code 🔎 Unravel the fix

In Spring and enterprise code

Inside a @Transactional method the exception may only surface at commit time, after your catch block, because JPA flushes late. Call saveAndFlush to fail early.

Debug it faster

Paste the whole stack trace into the stack trace beautifier to hide framework frames, jump to the root cause and find the first line of your own code. It runs in your browser, so the trace never leaves your machine.

Related exceptions