Why Spring @Transactional Skips Checked Exceptions—and How to Ensure Proper Rollback

Spring @Transactional Default Rollback and Common Pitfalls

In Spring, the @Transactional annotation provides declarative transaction management, greatly simplifying transaction control code. However, its default rollback behavior can trap many developers.

1. Default Rollback Rules

The annotation has a key attribute rollbackFor that specifies which exceptions trigger a rollback. By default (when rollbackFor is not set), Spring only rolls back for RuntimeException and its subclasses (i.e., unchecked exceptions). Checked exceptions such as IOException do not cause an automatic rollback.

2. Java Exception Hierarchy Overview

Throwable

: Superclass of all errors and exceptions. Exception: Exceptions that an application can handle. RuntimeException: Unchecked exceptions (e.g., NullPointerException, ArrayIndexOutOfBoundsException) that do not require mandatory handling.

Checked Exception : All Exception subclasses except RuntimeException. They must be either caught with try‑catch or declared with throws (e.g., IOException, SQLException).

3. Problem Scenario Caused by Default Rollback

Consider a money‑transfer service that debits account A, credits account B, and then calls an external system which may throw a checked IOException:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.io.IOException;

@Service
public class TransferService {
    @Autowired
    private AccountRepository accountRepository;

    /**
     * Incorrect example: with default @Transactional the transaction may not roll back
     */
    @Transactional // uses default rollbackFor = RuntimeException.class
    public void transferMoney(String fromAccount, String toAccount, double amount) throws IOException {
        // 1. debit fromAccount
        accountRepository.debit(fromAccount, amount);
        // 2. credit toAccount
        accountRepository.credit(toAccount, amount);
        // 3. call external system that may throw IOException
        callExternalSystem(); // declared throws IOException
    }

    private void callExternalSystem() throws IOException {
        // Simulate an IO failure
        throw new IOException("Failed to communicate with external system");
    }
}

interface AccountRepository {
    void debit(String accountNumber, double amount);
    void credit(String accountNumber, double amount);
}

Analysis of the method:

Database updates (debit and credit) are performed.

An external call may throw IOException (a checked exception).

Because the default configuration only rolls back for RuntimeException, the transaction does not roll back when IOException is thrown.

The result is money transferred in the database while the external system call fails, leading to severe data inconsistency.

4. Solution: Explicitly Specify rollbackFor

To avoid this pitfall, always declare the exceptions that should trigger a rollback:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.io.IOException;

@Service
public class TransferServiceFixed {
    @Autowired
    private AccountRepository accountRepository;

    /** Recommended: explicitly specify all exceptions that must cause a rollback */
    @Transactional(rollbackFor = { Exception.class }) // rolls back for any Exception, including checked ones
    // Or more specific: @Transactional(rollbackFor = { IOException.class, SQLException.class })
    public void transferMoney(String fromAccount, String toAccount, double amount) throws IOException {
        // 1. debit fromAccount
        accountRepository.debit(fromAccount, amount);
        // 2. credit toAccount
        accountRepository.credit(toAccount, amount);
        // 3. call external system
        callExternalSystem();
    }

    private void callExternalSystem() throws IOException {
        // Simulate an IO failure
        throw new IOException("Failed to communicate with external system");
    }
}

interface AccountRepository {
    void debit(String accountNumber, double amount);
    void credit(String accountNumber, double amount);
}

By using @Transactional(rollbackFor = { Exception.class }), Spring will roll back the transaction for any exception type, including checked exceptions like IOException. If you only want specific checked exceptions to trigger a rollback, list them explicitly as shown.

5. Summary

The @Transactional annotation is powerful but its default behavior rolls back only for runtime exceptions. When business logic involves checked exceptions that should cancel the transaction, remember to use the rollbackFor attribute to override the default. This practice prevents data inconsistency caused by unhandled checked exceptions.