MySQL NDB Cluster API Developer Guide

2.3.15 The NdbError Structure

This section provides information about the NdbError data structure, which contains status and other information about errors, including error codes, classifications, and messages.

NdbError Overview

Description

An NdbError consists of six parts, listed here, of which one is deprecated:

  1. Error status: This describes the impact of an error on the application, and reflects what the application should do when the error is encountered.

    The error status is described by a value of the Status type. See NdbError::Status, for possible Status values and how they should be interpreted.

  2. Error classification: This represents a logical error type or grouping.

    The error classification is described by a value of the Classification type. See NdbError::Classification, for possible classifications and their interpretation. Additional information is provided in Section 2.4.4, “NDB Error Classifications”.

  3. Error code: This is an NDB API internal error code which uniquely identifies the error.

    Important

    It is not recommended to write application programs which are dependent on specific error codes. Instead, applications should check error status and classification. More information about errors can also be obtained by checking error messages and (when available) error detail messages. However—like error codes—these error messages and error detail messages are subject to change.

    A listing of current error codes, broken down by classification, is provided in Section 2.4.2, “NDB Error Codes: by Type”. This listing is updated with new NDB Cluster releases. You can also check the file storage/ndb/src/ndbapi/ndberror.c in the NDB Cluster sources.

  4. MySQL Error code: This is the corresponding MySQL Server error code. MySQL error codes are not discussed in this document; please see Server Error Message Reference, in the MySQL Manual, for information about these.

  5. Error message: This is a generic, context-independent description of the error.

  6. Error details: This can often provide additional information (not found in the error message) about an error, specific to the circumstances under which the error is encountered. However, it is not available in all cases.

    Where not specified, the error detail message is NULL.

    Note

    This property is deprecated and scheduled for eventual removal. For obtaining error details, you should use the Ndb::getNdbErrorDetail() method instead.

Specific NDB API error codes, messages, and detail messages are subject to change without notice.

Definition

The NdbError structure contains the following members, whose types are as shown here:

  • Status status: The error status.

  • Classification classification: The error type (classification).

  • int code: The NDB API error code.

  • int mysql_code: The MySQL error code.

  • const char* message: The error message.

  • char* details: The error detail message.

    details is deprecated and scheduled for eventual removal. You should use the Ndb::getNdbErrorDetail() method instead. (Bug #48851)

Types

NdbError defines the two data types listed here:

  • Classification: The type of error or the logical grouping to which the error belongs.

  • Status: The error status.

NdbError::Classification

This section provides information about the Classification data type.

Description

This type describes the type of error, or the logical group to which it belongs.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.39 NdbError Classification data type values and descriptions

Name Description
NoError Indicates success (no error occurred)
ApplicationError An error occurred in an application program
NoDataFound A read operation failed due to one or more missing records.
ConstraintViolation A constraint violation occurred, such as attempting to insert a tuple having a primary key value already in use in the target table.
SchemaError An error took place when trying to create or use a table.
InsufficientSpace There was insufficient memory for data or indexes.
TemporaryResourceError This type of error is typically encountered when there are too many active transactions.
NodeRecoveryError This is a temporary failure which was likely caused by a node recovery in progress, some examples being when information sent between an application and NDB is lost, or when there is a distribution change.
OverloadError This type of error is often caused when there is insufficient log file space.
TimeoutExpired A timeout, often caused by a deadlock.
UnknownResultError It is not known whether a transaction was committed.
InternalError A serious error has occurred in NDB itself.
FunctionNotImplemented The application attempted to use a function which is not yet implemented.
UnknownErrorCode This is seen where the NDB error handler cannot determine the correct error code to report.
NodeShutdown This is caused by a node shutdown.
SchemaObjectExists The application attempted to create a schema object that already exists.
InternalTemporary A request was sent to a node other than the master.

Related information specific to certain error conditions can be found in Section 2.4.2, “NDB Error Codes: by Type”, and in Section 2.4.4, “NDB Error Classifications”.

NdbError::Status

This section provides information about the Status data type.

Description

This type is used to describe an error's status.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.40 NdbError Status data type values and descriptions

Name Description
Success No error has occurred
TemporaryError A temporary and usually recoverable error; the application should retry the operation giving rise to the error
PermanentError Permanent error; not recoverable
UnknownResult The operation's result or status is unknown

Related information specific to certain error conditions can be found in Section 2.4.4, “NDB Error Classifications”.