SQLException (Java Platform SE 8 )
Keywords: java.sql.SQLException class
Date: 2026-04-17

compact2, compact3
java.sql

## Class SQLException

- java.lang.Object
- - java.lang.Throwable
  - - java.lang.Exception
    - - java.sql.SQLException

- All Implemented Interfaces:
    Serializable, Iterable<Throwable>
  Direct Known Subclasses:
    BatchUpdateException, RowSetWarning, SerialException, SQLClientInfoException, SQLNonTransientException, SQLRecoverableException, SQLTransientException, SQLWarning, SyncFactoryException, SyncProviderException

      public class SQLException
      extends Exception
      implements Iterable<Throwable>

  An exception that provides information on a database access error or other errors.

  Each `SQLException` provides several kinds of information:

  - a string describing the error. This is used as the Java Exception message, available via the method `getMesasge`.
  - a "SQLstate" string, which follows either the XOPEN SQLstate conventions or the SQL:2003 conventions. The values of the SQLState string are described in the appropriate spec. The `DatabaseMetaData` method `getSQLStateType` can be used to discover whether the driver returns the XOPEN type or the SQL:2003 type.
  - an integer error code that is specific to each vendor. Normally this will be the actual error code returned by the underlying database.
  - a chain to a next Exception. This can be used to provide additional error information.
  - the causal relationship, if any for this `SQLException`.
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SQLException()` Constructs a `SQLException` object.
    `SQLException(String reason)` Constructs a `SQLException` object with a given `reason`.
    `SQLException(String reason, String SQLState)` Constructs a `SQLException` object with a given `reason` and `SQLState`.
    `SQLException(String reason, String SQLState, int vendorCode)` Constructs a `SQLException` object with a given `reason`, `SQLState` and `vendorCode`.
    `SQLException(String reason, String sqlState, int vendorCode, Throwable cause)` Constructs a `SQLException` object with a given `reason`, `SQLState`, `vendorCode` and `cause`.
    `SQLException(String reason, String sqlState, Throwable cause)` Constructs a `SQLException` object with a given `reason`, `SQLState` and `cause`.
    `SQLException(String reason, Throwable cause)` Constructs a `SQLException` object with a given `reason` and `cause`.
    `SQLException(Throwable cause)` Constructs a `SQLException` object with a given `cause`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getErrorCode()` Retrieves the vendor-specific exception code for this `SQLException` object.
    `SQLException` | `getNextException()` Retrieves the exception chained to this `SQLException` object by setNextException(SQLException ex).
    `String` | `getSQLState()` Retrieves the SQLState for this `SQLException` object.
    `Iterator<Throwable>` | `iterator()` Returns an iterator over the chained SQLExceptions.
    `void` | `setNextException(SQLException ex)` Adds an `SQLException` object to the end of the chain.

    - ### Methods inherited from class java.lang.Throwable

      `addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### SQLException

          public SQLException(String reason,
                              String SQLState,
                              int vendorCode)

      Constructs a `SQLException` object with a given `reason`, `SQLState` and `vendorCode`. The `cause` is not initialized, and may subsequently be initialized by a call to the `Throwable.initCause(java.lang.Throwable)` method.

      Parameters:
        `reason` - a description of the exception
        `SQLState` - an XOPEN or SQL:2003 code identifying the exception
        `vendorCode` - a database vendor-specific exception code

    - #### SQLException

          public SQLException(String reason,
                              String SQLState)

      Constructs a `SQLException` object with a given `reason` and `SQLState`. The `cause` is not initialized, and may subsequently be initialized by a call to the `Throwable.initCause(java.lang.Throwable)` method. The vendor code is initialized to 0.

      Parameters:
        `reason` - a description of the exception
        `SQLState` - an XOPEN or SQL:2003 code identifying the exception

    - #### SQLException

          public SQLException(String reason)

      Constructs a `SQLException` object with a given `reason`. The `SQLState` is initialized to `null` and the vendor code is initialized to 0. The `cause` is not initialized, and may subsequently be initialized by a call to the `Throwable.initCause(java.lang.Throwable)` method.

      Parameters:
        `reason` - a description of the exception

    - #### SQLException

          public SQLException()

      Constructs a `SQLException` object. The `reason`, `SQLState` are initialized to `null` and the vendor code is initialized to 0. The `cause` is not initialized, and may subsequently be initialized by a call to the `Throwable.initCause(java.lang.Throwable)` method.

    - #### SQLException

          public SQLException(Throwable cause)

      Constructs a `SQLException` object with a given `cause`. The `SQLState` is initialized to `null` and the vendor code is initialized to 0. The `reason` is initialized to `null` if `cause==null` or to `cause.toString()` if `cause!=null`.

      Parameters:
        `cause` - the underlying reason for this `SQLException` (which is saved for later retrieval by the `getCause()` method); may be null indicating the cause is non-existent or unknown.
      Since:
        1.6

    - #### SQLException

          public SQLException(String reason,
                              Throwable cause)

      Constructs a `SQLException` object with a given `reason` and `cause`. The `SQLState` is initialized to `null` and the vendor code is initialized to 0.

      Parameters:
        `reason` - a description of the exception.
        `cause` - the underlying reason for this `SQLException` (which is saved for later retrieval by the `getCause()` method); may be null indicating the cause is non-existent or unknown.
      Since:
        1.6

    - #### SQLException

          public SQLException(String reason,
                              String sqlState,
                              Throwable cause)

      Constructs a `SQLException` object with a given `reason`, `SQLState` and `cause`. The vendor code is initialized to 0.

      Parameters:
        `reason` - a description of the exception.
        `sqlState` - an XOPEN or SQL:2003 code identifying the exception
        `cause` - the underlying reason for this `SQLException` (which is saved for later retrieval by the `getCause()` method); may be null indicating the cause is non-existent or unknown.
      Since:
        1.6

    - #### SQLException

          public SQLException(String reason,
                              String sqlState,
                              int vendorCode,
                              Throwable cause)

      Constructs a `SQLException` object with a given `reason`, `SQLState`, `vendorCode` and `cause`.

      Parameters:
        `reason` - a description of the exception
        `sqlState` - an XOPEN or SQL:2003 code identifying the exception
        `vendorCode` - a database vendor-specific exception code
        `cause` - the underlying reason for this `SQLException` (which is saved for later retrieval by the `getCause()` method); may be null indicating the cause is non-existent or unknown.
      Since:
        1.6

  - ### Method Detail

    - #### getSQLState

          public String getSQLState()

      Retrieves the SQLState for this `SQLException` object.
      Returns:
        the SQLState value

    - #### getErrorCode

          public int getErrorCode()

      Retrieves the vendor-specific exception code for this `SQLException` object.
      Returns:
        the vendor's error code

    - #### getNextException

          public SQLException getNextException()

      Retrieves the exception chained to this `SQLException` object by setNextException(SQLException ex).
      Returns:
        the next `SQLException` object in the chain; `null` if there are none
      See Also:
        `setNextException(java.sql.SQLException)`

    - #### setNextException

          public void setNextException(SQLException ex)

      Adds an `SQLException` object to the end of the chain.
      Parameters:
        `ex` - the new exception that will be added to the end of the `SQLException` chain
      See Also:
        `getNextException()`

    - #### iterator

          public Iterator<Throwable> iterator()

      Returns an iterator over the chained SQLExceptions. The iterator will be used to iterate over each SQLException and its underlying cause (if any).
      Specified by:
        `iterator` in interface `Iterable<Throwable>`
      Returns:
        an iterator over the chained SQLExceptions and causes in the proper order
      Since:
        1.6

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2026, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.