Version 2.9.2
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-specific error codes always appear in the -31,800 to -31,999 range.

The following is a list of possible WiredTiger-specific errors:

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.
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 the application exit and restart. The application can exit immediately when WT_PANIC is returned from a WiredTiger interface, no further WiredTiger calls are required.
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 only generated when wiredtiger_open is configured to run in-memory, and an insert or update 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.

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));
return (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));
return (ret);
}

Note that wiredtiger_strerror is not thread-safe.

Error handling using the WT_EVENT_HANDLER

More complex error handling can be configured by passing an implementation of WT_EVENT_HANDLER to wiredtiger_open or WT_CONNECTION::open_session.

For example, both informational and error messages might be passed to an application-specific logging function that added a timestamp and logged the message to a file, and error messages might additionally be output to the stderr file stream.

/*
* Create our own event handler structure to allow us to pass context through
* to event handler callbacks. For this to work the WiredTiger event handler
* must appear first in our custom event handler structure.
*/
typedef struct {
const char *app_id;
} CUSTOM_EVENT_HANDLER;
/*
* handle_wiredtiger_error --
* Function to handle error callbacks from WiredTiger.
*/
int
handle_wiredtiger_error(WT_EVENT_HANDLER *handler,
WT_SESSION *session, int error, const char *message)
{
CUSTOM_EVENT_HANDLER *custom_handler;
/* Cast the handler back to our custom handler. */
custom_handler = (CUSTOM_EVENT_HANDLER *)handler;
/* Report the error on the console. */
fprintf(stderr,
"app_id %s, thread context %p, error %d, message %s\n",
custom_handler->app_id, (void *)session, error, message);
return (0);
}
/*
* handle_wiredtiger_message --
* Function to handle message callbacks from WiredTiger.
*/
int
handle_wiredtiger_message(
WT_EVENT_HANDLER *handler, WT_SESSION *session, const char *message)
{
/* Cast the handler back to our custom handler. */
printf("app id %s, thread context %p, message %s\n",
((CUSTOM_EVENT_HANDLER *)handler)->app_id,
(void *)session, message);
return (0);
}
CUSTOM_EVENT_HANDLER event_handler;
event_handler.h.handle_error = handle_wiredtiger_error;
event_handler.h.handle_message = handle_wiredtiger_message;
/* Set handlers to NULL to use the default handler. */
event_handler.h.handle_progress = NULL;
event_handler.h.handle_close = NULL;
event_handler.app_id = "example_event_handler";
ret = wiredtiger_open(home,
(WT_EVENT_HANDLER *)&event_handler, "create", &conn);