Error handling in Java

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.

Informational return values, like wiredtiger.WT_NOTFOUND or wiredtiger.WT_DUPLICATE_KEY or 0 (success), are directly returned by APIs. More severe errors are thrown as WiredTigerException, which may be caught by the application.

The WiredTigerRollbackException is a specific type of WiredTigerException, thrown when there is a conflict between concurrent operations. An application that catches this exception should call rollback() on the relevant transaction, and retry as necessary.

The WiredTigerPanicException is a specific type of WiredTigerException, thrown when there is a fatal error requiring database restart. Applications will normally handle WiredTigerPanicException as a special case. A correctly-written WiredTiger application will likely catch WiredTigerPanicException and immediately exit or otherwise handle fatal errors. Note that no further WiredTiger calls are required after WiredTigerPanicException is caught (and further calls will themselves immediately fail).

The following is a complete list of possible WiredTiger-specific return values, all constants defined in the com.wiredtiger.db.wiredtiger class:

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 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 Cursor.update or 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 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 Session.strerror and wiredtiger_strerror functions return the standard text message associated with any WiredTiger, ISO C, or POSIX standard API.

    try {
        String key = "non-existent key";
        cursor.putKeyString(key);
        if ((ret = cursor.remove()) != 0) {
            System.err.println(
                "cursor.remove: " + wiredtiger.wiredtiger_strerror(ret));
            return (ret);
        }
    } catch (WiredTigerException wte) {  /* Catch severe errors. */
        System.err.println("cursor.remove exception: " + wte);
    }

    try {
        String key = "non-existent key";
        cursor.putKeyString(key);
        if ((ret = cursor.remove()) != 0) {
            System.err.println(
                "cursor.remove: " + wiredtiger.wiredtiger_strerror(ret));
            return (ret);
        }
    } catch (WiredTigerException wte) {  /* Catch severe errors. */
        System.err.println("cursor.remove exception: " + wte);
    }

Note that wiredtiger_strerror is not thread-safe.