Java SQLException chains: preserve SQLState and linked failures

Operational contract

The method walks at most 47 linked SQLException objects and returns their SQLState and vendor code as immutable entries. It uses getNextException, which is distinct from the normal cause chain. SQLState can be null, so this sample emits UNKNOWN. A service should classify known states under its database policy and preserve the original exception for logging or propagation; collapsing everything to a message string loses useful detail. Do not expose vendor messages directly to clients because they can reveal SQL or data values.

Failure case

A batched write fails and the driver links a primary transaction error to a detailed constraint failure. Recording only the first message loses the later SQLState. This helper retains both codes for an internal decision, while the caller still handles rollback and request response.

Java code

import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;

public class SqlFailureCodes {
    public record Code(String state, int vendorCode) { }

    public static List<Code> inspect(SQLException failure) {
        List<Code> codes = new ArrayList<>();
        for (SQLException current = failure; current != null;
                current = current.getNextException()) {
            if (codes.size() == 47) throw new IllegalStateException("Exception chain exceeds cap");
            String state = current.getSQLState();
            codes.add(new Code(state == null ? "UNKNOWN" : state, current.getErrorCode()));
        }
        return List.copyOf(codes);
    }
}

Performance and ownership cost

Walking E linked exceptions costs O(E) time and O(E) result storage, capped at 47. It does not query the database. A chain cap prevents pathological diagnostic traversal from monopolizing error handling.

Common Mistakes

• Do not discard next exceptions when diagnosing a batch failure.
• Do not assume SQLState is always non-null or portable across vendors.
• Do not send raw database exception messages to external clients.

Connected lessons

• Java JDBC batches: inspect update counts and own rollback
• Java SQLWarning: inspect nonfatal database diagnostics before reuse
• Java exceptions: recovery boundaries and failure context
• Java DatabaseMetaData: check features before depending on them
• Java JDBC cursor holdability: choose what commit does to a ResultSet
• Java JDBC boundary contracts quiz
• Advanced Java