Exception Handling

NuoDB supports mapping from common error states to categorized SQL exceptions. This allows the JDBC programmer to better handle specific SQL error states. There are two types of categorized SQL exceptions thrown by NuoDB: SQLNonTransientException and SQLTransientException. To obtain more information about an error, use SQLException#getErrorCode().

Non-Transient SQL Exceptions

A non-transient SQLException is thrown when a retry of the same operation would fail unless the cause of the SQL exception is corrected. Upon receiving a non-transient SQL exception, the application can assume that the connection is still valid.

SQLState NonTransient SQLException
08 SQLNonTransientConnectionException on initial attempt (i.e. Driver#connect())
0A SQLFeatureNotSupportedException
22 SQLDataException
23 SQLIntegrityConstraintViolationException
28 SQLInvalidAuthorizationException
42 SQLSyntaxErrorException

Transient SQL Exceptions

A transient SQLException is thrown when a previously failed operation might be able to succeed when the operation is retried without any intervention by application-level functionality.

SQLState Transient SQLException
08 SQLTransientConnectionException on attempt where we once had a connection but no longer do
40 SQLTransactionRollbackException

Obtaining Error Information

You can use the SQLException#getErrorCode() function to obtain more information about an error. For example, you might need to distinguish between a unique constraint violation and a check constraint violation. When handling the exception, check the error code. For a unique constraint violation the error code is -27. For a check constraint violation the error code is -45. See SQL Error Codes.

For example:

try {
} catch (SQLException e) {
    if (e.getErrorCode() == SQLState.UNIQUE_DUPLICATE.getCode()) {
        System.err.println("Unexpected duplicate");
    } else if (e.getErrorCode() == SQLState.CONSTRAINT_ERROR.getCode()) {
        System.err.println("Constraint violation");
    } else {
        System.err.println("Unexpected error: \"" + e.getMessage() + "\"");


BatchUpdateException supports exception chaining and when you call getNextException() on a BatchUpdateException object, it will traverse the list of exceptions that were generated. The catch clause for a BatchUpdateException could be like this example:

    } catch (BatchUpdateException bue) {

        int[] updateCounts = bue.getUpdateCounts();
        SQLException exception = bue;
        for (int i = 0; i < updateCounts.length; i++) {
                "** BatchUpdateException updateCounts[" + i + "]=\"" + 
                updateCounts[i] + 
                "\"" );
            if (updateCounts[i] == java.sql.Statement.EXECUTE_FAILED) {
                exception = exception.getNextException();
                System.out.println("   SQLException \"" + exception + "\"");

Suppose the output from this example looked as follows:

** BatchUpdateException updateCounts[0]="1"
** BatchUpdateException updateCounts[1]="1"
** BatchUpdateException updateCounts[2]="-3"
   SQLException "java.sql.SQLIntegrityConstraintViolationException: violation of constraint "GENDER""
** BatchUpdateException updateCounts[3]="1"
** BatchUpdateException updateCounts[4]="-3"
   SQLException "java.sql.SQLIntegrityConstraintViolationException: duplicate value in unique index MEMBERS..PRIMARY_KEY, key = '4'"
** BatchUpdateException updateCounts[5]="1"

This would tell us that six statements were executed by this batch update. NuoDB will always continue executing statements in a batch update, even after an error is incurred. The 3rd statement in the batch resulted in the error, "java.sql.SQLIntegrityConstraintViolationException: violation of constraint "GENDER"" and the 5th statement in the batch resulted in the error, "java.sql.SQLIntegrityConstraintViolationException: duplicate value in unique index MEMBERS..PRIMARY_KEY, key = '4'".