Version 12.0.0
Error handling

WiredTiger operations return a value of 0 on success and a non-zero value on error. Error codes may be either positive or negative: positive error codes are standard error codes as described for POSIX-like systems (for example, EINVAL or EBUSY), negative error codes are WiredTiger-specific (for example, WT_ROLLBACK). WiredTiger makes no guarantees about which error codes can be returned its APIs.

EBUSY errors

WiredTiger returns EBUSY for operations requiring exclusive access, when an object is not available for exclusive access. These operations include the WT_SESSION::alter, WT_SESSION::drop, WT_SESSION::salvage and WT_SESSION::verify methods, all of which will return EBUSY and fail if there are open cursors on the target object. Internal WiredTiger threads may temporarily open cursors on objects (for example, threads performing operations like statistics logging), and in that case operations may temporarily fail and return EBUSY when there are no application cursors open on the object. In this case, simply retrying the operation should be sufficient.

Additionally, unwritten data in the WiredTiger cache will prevent exclusive access to objects. In this case, calling the WT_SESSION:checkpoint method to perform a database checkpoint should resolve the problem, allowing a subsequent retry of the operation requiring exclusive access to succeed. Further failures imply other threads of control simultaneously updating the object in cache. Repeatedly calling checkpoint will race with those threads, and it's unspecified when or even if exclusive access to the object will be granted. Generally, applications will not call WiredTiger methods requiring exclusive access when the objects might be in active use by other threads.

WiredTiger-specific errors

WiredTiger-specific error codes are allocated from -31,800 to -31,999, inclusive. The following is a list of the WiredTiger-specific return values:

WT_ROLLBACK
This error is generated when an operation cannot be completed due to a conflict with concurrent operations. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.
WT_DUPLICATE_KEY
This error is generated when the application attempts to insert a record with the same key as an existing record without the 'overwrite' configuration to WT_SESSION::open_cursor.
WT_ERROR
This error is returned when an error is not covered by a specific error return. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.
WT_NOTFOUND
This error indicates an operation did not find a value to return. This includes cursor search and other operations where no record matched the cursor's search key such as WT_CURSOR::update or WT_CURSOR::remove.
WT_PANIC
This error indicates an underlying problem that requires a database restart. The application may exit immediately, no further WiredTiger calls are required (and further calls will themselves immediately fail).
WT_RUN_RECOVERY
This error is generated when wiredtiger_open is configured to return an error if recovery is required to use the database.
WT_CACHE_FULL
This error is generated when wiredtiger_open is configured to run in-memory, and a data modification operation requires more than the configured cache size to complete. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.
WT_PREPARE_CONFLICT
This error is generated when the application attempts to read an updated record which is part of a transaction that has been prepared but not yet resolved.
WT_TRY_SALVAGE
This error is generated when corruption is detected in an on-disk file. During normal operations, this may occur in rare circumstances as a result of a system crash. The application may choose to salvage the file or retry wiredtiger_open with the 'salvage=true' configuration setting.

WiredTiger-specific sub-level errors

WiredTiger-specific error codes are allocated from -32,000 to -32,199, inclusive. The following is a list of the WiredTiger-specific return values:

WT_NONE
This sub-level error code is returned by default and indicates that no further context exists or is necessary.
WT_BACKGROUND_COMPACT_ALREADY_RUNNING
This sub-level error returns when the user tries to reconfigure background compaction while it is already running.
WT_SESSION_MAX
This sub-level error returns when the user has created more than the maximum number of sessions configured (including internal sessions).
WT_CACHE_OVERFLOW
This sub-level error indicates that the configured cache has exceeded full capacity.
WT_WRITE_CONFLICT
This sub-level error indicates that there is a write conflict on the same page between concurrent operations.
WT_OLDEST_FOR_EVICTION
This sub-level error indicates that a given transaction has the oldest transaction ID and needs to be rolled back.
WT_CONFLICT_BACKUP
This sub-level error indicates that there is conflict perform the operation because of a running backup in the system.
WT_CONFLICT_DHANDLE
This sub-level error indicates that a concurrent operation is holding the data handle of the table.
WT_CONFLICT_SCHEMA_LOCK
This sub-level error indicates that a concurrent operation is performing a schema type operation or currently holds the schema lock.
WT_UNCOMMITTED_DATA
This sub-level error returns when the table has uncommitted data.
WT_DIRTY_DATA
This sub-level error returns when the table has dirty content.
WT_CONFLICT_TABLE_LOCK
This sub-level error indicates that a concurrent operation is performing a table operation.
WT_CONFLICT_CHECKPOINT_LOCK
This sub-level error indicates that a concurrent operation is performing a checkpoint.

Translating errors

The WT_SESSION::strerror and wiredtiger_strerror functions return the standard text message associated with any WiredTiger, ISO C, or POSIX standard API.

const char *key = "non-existent key";
cursor->set_key(cursor, key);
if ((ret = cursor->remove(cursor)) != 0)
fprintf(stderr, "cursor.remove: %s\n", cursor->session->strerror(cursor->session, ret));
const char *key = "non-existent key";
cursor->set_key(cursor, key);
if ((ret = cursor->remove(cursor)) != 0)
fprintf(stderr, "cursor.remove: %s\n", wiredtiger_strerror(ret));

Note that wiredtiger_strerror is not thread-safe.

wiredtiger_strerror
const char * wiredtiger_strerror(int error)
Return information about a WiredTiger error as a string (see WT_SESSION::strerror for a thread-safe A...
WT_CURSOR::remove
int remove(WT_CURSOR *cursor)
Remove a record.
WT_CURSOR::set_key
void set_key(WT_CURSOR *cursor,...)
Set the key for the next operation.
WT_CURSOR::session
WT_SESSION * session
The session handle for this cursor.
Definition: wiredtiger.in:198
WT_SESSION::strerror
const char * strerror(WT_SESSION *session, int error)
Return information about an error as a string.