Result and Error Codes Small. Fast. Reliable. Choose any three. Home Menu About Documentation Download License Support Purchase Search About Documentation Download Support Purchase Search Documentation Search Changelog Result and Error Codes Table Of Contents 1. Result Codes versus Error Codes 2. Primary Result Codes versus Extended Result Codes 3. Definitions 4. Primary Result Code List 5. Extended Result Code List 6. Result Code Meanings Overview Many of the routines in the SQLite C-language Interface return numeric result codes indicating either success or failure, and in the event of a failure, providing some idea of the cause of the failure. This document strives to explain what each of those numeric result codes means. 1. Result Codes versus Error Codes "Error codes" are a subset of "result codes" that indicate that something has gone wrong. There are only a few non-error result codes: SQLITE_OK, SQLITE_ROW, and SQLITE_DONE. The term "error code" means any result code other than these three. 2. Primary Result Codes versus Extended Result Codes Result codes are signed 32-bit integers. The least significant 8 bits of the result code define a broad category and are called the "primary result code". More significant bits provide more detailed information about the error and are called the "extended result code." Note that the primary result code is always a part of the extended result code. Given a full 32-bit extended result code, the application can always find the corresponding primary result code merely by extracting the least significant 8 bits of the extended result code. All extended result codes are also error codes. Hence the terms "extended result code" and "extended error code" are interchangeable. For historic compatibility, the C-language interfaces return primary result codes by default. The extended result code for the most recent error can be retrieved using the sqlite3_extended_errcode() interface. The sqlite3_extended_result_codes() interface can be used to put a database connection into a mode where it returns the extended result codes instead of the primary result codes. 3. Definitions All result codes are integers. Symbolic names for all result codes are created using "#define" macros in the sqlite3.h header file. There are separate sections in the sqlite3.h header file for the result code definitions and the extended result code definitions. Primary result code symbolic names are of the form "SQLITE_XXXXXX" where XXXXXX is a sequence of uppercase alphabetic characters. Extended result code names are of the form "SQLITE_XXXXXX_YYYYYYY" where the XXXXXX part is the corresponding primary result code and the YYYYYYY is an extension that further classifies the result code. The names and numeric values for existing result codes are fixed and unchanging. However, new result codes, and especially new extended result codes, might appear in future releases of SQLite. 4. Primary Result Code List The 31 result codes are defined in sqlite3.h and are listed in alphabetical order below: SQLITE_ABORT (4) SQLITE_AUTH (23) SQLITE_BUSY (5) SQLITE_CANTOPEN (14) SQLITE_CONSTRAINT (19) SQLITE_CORRUPT (11) SQLITE_DONE (101) SQLITE_EMPTY (16) SQLITE_ERROR (1) SQLITE_FORMAT (24) SQLITE_FULL (13) SQLITE_INTERNAL (2) SQLITE_INTERRUPT (9) SQLITE_IOERR (10) SQLITE_LOCKED (6) SQLITE_MISMATCH (20) SQLITE_MISUSE (21) SQLITE_NOLFS (22) SQLITE_NOMEM (7) SQLITE_NOTADB (26) SQLITE_NOTFOUND (12) SQLITE_NOTICE (27) SQLITE_OK (0) SQLITE_PERM (3) SQLITE_PROTOCOL (15) SQLITE_RANGE (25) SQLITE_READONLY (8) SQLITE_ROW (100) SQLITE_SCHEMA (17) SQLITE_TOOBIG (18) SQLITE_WARNING (28) 5. Extended Result Code List The 74 extended result codes are defined in sqlite3.h and are listed in alphabetical order below: SQLITE_ABORT_ROLLBACK (516) SQLITE_AUTH_USER (279) SQLITE_BUSY_RECOVERY (261) SQLITE_BUSY_SNAPSHOT (517) SQLITE_BUSY_TIMEOUT (773) SQLITE_CANTOPEN_CONVPATH (1038) SQLITE_CANTOPEN_DIRTYWAL (1294) SQLITE_CANTOPEN_FULLPATH (782) SQLITE_CANTOPEN_ISDIR (526) SQLITE_CANTOPEN_NOTEMPDIR (270) SQLITE_CANTOPEN_SYMLINK (1550) SQLITE_CONSTRAINT_CHECK (275) SQLITE_CONSTRAINT_COMMITHOOK (531) SQLITE_CONSTRAINT_DATATYPE (3091) SQLITE_CONSTRAINT_FOREIGNKEY (787) SQLITE_CONSTRAINT_FUNCTION (1043) SQLITE_CONSTRAINT_NOTNULL (1299) SQLITE_CONSTRAINT_PINNED (2835) SQLITE_CONSTRAINT_PRIMARYKEY (1555) SQLITE_CONSTRAINT_ROWID (2579) SQLITE_CONSTRAINT_TRIGGER (1811) SQLITE_CONSTRAINT_UNIQUE (2067) SQLITE_CONSTRAINT_VTAB (2323) SQLITE_CORRUPT_INDEX (779) SQLITE_CORRUPT_SEQUENCE (523) SQLITE_CORRUPT_VTAB (267) SQLITE_ERROR_MISSING_COLLSEQ (257) SQLITE_ERROR_RETRY (513) SQLITE_ERROR_SNAPSHOT (769) SQLITE_IOERR_ACCESS (3338) SQLITE_IOERR_AUTH (7178) SQLITE_IOERR_BEGIN_ATOMIC (7434) SQLITE_IOERR_BLOCKED (2826) SQLITE_IOERR_CHECKRESERVEDLOCK (3594) SQLITE_IOERR_CLOSE (4106) SQLITE_IOERR_COMMIT_ATOMIC (7690) SQLITE_IOERR_CONVPATH (6666) SQLITE_IOERR_CORRUPTFS (8458) SQLITE_IOERR_DATA (8202) SQLITE_IOERR_DELETE (2570) SQLITE_IOERR_DELETE_NOENT (5898) SQLITE_IOERR_DIR_CLOSE (4362) SQLITE_IOERR_DIR_FSYNC (1290) SQLITE_IOERR_FSTAT (1802) SQLITE_IOERR_FSYNC (1034) SQLITE_IOERR_GETTEMPPATH (6410) SQLITE_IOERR_LOCK (3850) SQLITE_IOERR_MMAP (6154) SQLITE_IOERR_NOMEM (3082) SQLITE_IOERR_RDLOCK (2314) SQLITE_IOERR_READ (266) SQLITE_IOERR_ROLLBACK_ATOMIC (7946) SQLITE_IOERR_SEEK (5642) SQLITE_IOERR_SHMLOCK (5130) SQLITE_IOERR_SHMMAP (5386) SQLITE_IOERR_SHMOPEN (4618) SQLITE_IOERR_SHMSIZE (4874) SQLITE_IOERR_SHORT_READ (522) SQLITE_IOERR_TRUNCATE (1546) SQLITE_IOERR_UNLOCK (2058) SQLITE_IOERR_VNODE (6922) SQLITE_IOERR_WRITE (778) SQLITE_LOCKED_SHAREDCACHE (262) SQLITE_LOCKED_VTAB (518) SQLITE_NOTICE_RECOVER_ROLLBACK (539) SQLITE_NOTICE_RECOVER_WAL (283) SQLITE_OK_LOAD_PERMANENTLY (256) SQLITE_READONLY_CANTINIT (1288) SQLITE_READONLY_CANTLOCK (520) SQLITE_READONLY_DBMOVED (1032) SQLITE_READONLY_DIRECTORY (1544) SQLITE_READONLY_RECOVERY (264) SQLITE_READONLY_ROLLBACK (776) SQLITE_WARNING_AUTOINDEX (284) 6. Result Code Meanings The meanings for all 105 result code values are shown below, in numeric order. (0) SQLITE_OK The SQLITE_OK result code means that the operation was successful and that there were no errors. Most other result codes indicate an error. (1) SQLITE_ERROR The SQLITE_ERROR result code is a generic error code that is used when no other more specific error code is available. (2) SQLITE_INTERNAL The SQLITE_INTERNAL result code indicates an internal malfunction. In a working version of SQLite, an application should never see this result code. If application does encounter this result code, it shows that there is a bug in the database engine. This result code might be caused by a bug in SQLite. However, application-defined SQL functions or virtual tables, or VFSes, or other extensions can also cause this result code to be returned, so the problem might not be the fault of the core SQLite. (3) SQLITE_PERM The SQLITE_PERM result code indicates that the requested access mode for a newly created database could not be provided. (4) SQLITE_ABORT The SQLITE_ABORT result code indicates that an operation was aborted prior to completion, usually by application request. See also: SQLITE_INTERRUPT. If the callback function to sqlite3_exec() returns non-zero, then sqlite3_exec() will return SQLITE_ABORT. If a ROLLBACK operation occurs on the same database connection as a pending read or write, then the pending read or write may fail with an SQLITE_ABORT or SQLITE_ABORT_ROLLBACK error. In addition to being a result code, the SQLITE_ABORT value is also used as a conflict resolution mode returned from the sqlite3_vtab_on_conflict() interface. (5) SQLITE_BUSY The SQLITE_BUSY result code indicates that the database file could not be written (or in some cases read) because of concurrent activity by some other database connection, usually a database connection in a separate process. For example, if process A is in the middle of a large write transaction and at the same time process B attempts to start a new write transaction, process B will get back an SQLITE_BUSY result because SQLite only supports one writer at a time. Process B will need to wait for process A to finish its transaction before starting a new transaction. The sqlite3_busy_timeout() and sqlite3_busy_handler() interfaces and the busy_timeout pragma are available to process B to help it deal with SQLITE_BUSY errors. An SQLITE_BUSY error can occur at any point in a transaction: when the transaction is first started, during any write or update operations, or when the transaction commits. To avoid encountering SQLITE_BUSY errors in the middle of a transaction, the application can use BEGIN IMMEDIATE instead of just BEGIN to start a transaction. The BEGIN IMMEDIATE command might itself return SQLITE_BUSY, but if it succeeds, then SQLite guarantees that no subsequent operations on the same database through the next COMMIT will return SQLITE_BUSY. See also: SQLITE_BUSY_RECOVERY and SQLITE_BUSY_SNAPSHOT. The SQLITE_BUSY result code differs from SQLITE_LOCKED in that SQLITE_BUSY indicates a conflict with a separate database connection, probably in a separate process, whereas SQLITE_LOCKED indicates a conflict within the same database connection (or sometimes a database connection with a shared cache). (6) SQLITE_LOCKED The SQLITE_LOCKED result code indicates that a write operation could not continue because of a conflict within the same database connection or a conflict with a different database connection that uses a shared cache. For example, a DROP TABLE statement cannot be run while another thread is reading from that table on the same database connection because dropping the table would delete the table out from under the concurrent reader. The SQLITE_LOCKED result code differs from SQLITE_BUSY in that SQLITE_LOCKED indicates a conflict on the same database connection (or on a connection with a shared cache) whereas SQLITE_BUSY indicates a conflict with a different database connection, probably in a different process. (7) SQLITE_NOMEM The SQLITE_NOMEM result code indicates that SQLite was unable to allocate all the memory it needed to complete the operation. In other words, an internal call to sqlite3_malloc() or sqlite3_realloc() has failed in a case where the memory being allocated was required in order to continue the operation. (8) SQLITE_READONLY The SQLITE_READONLY result code is returned when an attempt is made to alter some data for which the current database connection does not have write permission. (9) SQLITE_INTERRUPT The SQLITE_INTERRUPT result code indicates that an operation was interrupted by the sqlite3_interrupt() interface. See also: SQLITE_ABORT (10) SQLITE_IOERR The SQLITE_IOERR result code says that the operation could not finish because the operating system reported an I/O error. A full disk drive will normally give an SQLITE_FULL error rather than an SQLITE_IOERR error. There are many different extended result codes for I/O errors that identify the specific I/O operation that failed. (11) SQLITE_CORRUPT The SQLITE_CORRUPT result code indicates that the database file has been corrupted. See the How To Corrupt Your Database Files for further discussion on how corruption can occur. (12) SQLITE_NOTFOUND The SQLITE_NOTFOUND result code is exposed in three ways: SQLITE_NOTFOUND can be returned by the sqlite3_file_control() interface to indicate that the file control opcode passed as the third argument was not recognized by the underlying VFS. SQLITE_NOTFOUND can also be returned by the xSetSystemCall() method of an sqlite3_vfs object. SQLITE_NOTFOUND can be returned by sqlite3_vtab_rhs_value() to indicate that the right-hand operand of a constraint is not available to the xBestIndex method that made the call. The SQLITE_NOTFOUND result code is also used internally by the SQLite implementation, but those internal uses are not exposed to the application. (13) SQLITE_FULL The SQLITE_FULL result code indicates that a write could not complete because the disk is full.…