PersistenceException

PersistenceException is a general, unchecked exception used by the Java Persistence API (JPA) and its implementations to indicate problems encountered while performing persistence operations. It extends RuntimeException, meaning it is not required to be caught or declared, and serves as a common base type for more specific persistence errors.

In the JPA specification, PersistenceException is the parent for several more specific exceptions including EntityExistsException, EntityNotFoundException, OptimisticLockException, and TransactionRequiredException. These subclasses provide more precise failure signals, but a provider may also throw PersistenceException directly when the problem does not fit a named subclass. Some providers further wrap JDBC or driver-level exceptions as the cause.

Causes of a PersistenceException include database connectivity issues, constraint violations (such as primary key or unique constraints), invalid entity state (such as persisting a detached entity or removing a non-managed entity), mapping or configuration errors, missing transactions, or SQL syntax errors generated by queries.

Handling a PersistenceException is shaped by its status as an unchecked exception. Applications may catch it to implement a generic recovery or logging policy, or rely on container-managed transactions to roll back on occurrence. When possible, catching more specific exceptions can allow tailored handling and more precise recovery actions. In practice, persistence providers often wrap underlying causes, such as SQLException, inside a PersistenceException, so examining the cause is often necessary to diagnose the failure.