10.4. Error Codes and Classes

Up: MPI Environmental Management Next: Error Classes, Error Codes, and Error Handlers Previous: Freeing Errorhandlers and Retrieving Error Strings

The error codes returned by MPI are left entirely to the implementation (with the exception of MPI_SUCCESS). This is done to allow an implementation to provide as much information as possible in the error code (for use with MPI_ERROR_STRING).

All MPI function calls shall return MPI_SUCCESS if and only if the specification of that function has been fulfilled at the point of return. For multiple completion functions, if the function returns MPI_ERR_IN_STATUS, the error code in each status object shall be set to MPI_SUCCESS if and only if the specification of the operation represented by the corresponding MPI_Request has been fulfilled at the point of return.

When an operation raises an error, it may not satisfy its specification (for example, a synchronizing operation may not have synchronized) and the content of the output buffers, targeted memory, or output parameters is undefined. However, a valid error code shall always be set when an operation raises an error, whether in the return value, error field in the status object, or element in an array of error codes.

To make it possible for an application to interpret an error code, the routine MPI_ERROR_CLASSconverts any error code into one of a small set of standard error codes, called error classes. Valid error classes are shown in Table 7 and Table 8.

Table 7: Error classes (Part 1)

MPI_ERR_ACCESS Permission denied
MPI_ERR_AMODE Error related to the amode passed to MPI_FILE_OPEN
MPI_ERR_ARG Invalid argument of some other kind
MPI_ERR_ASSERT Invalid assertion argument
MPI_ERR_BAD_FILE Invalid file name (e.g., path name too long)
MPI_ERR_BASE Invalid base passed to MPI_FREE_MEM
MPI_ERR_BUFFER Invalid buffer pointer argument
MPI_ERR_COMM Invalid communicator argument
MPI_ERR_CONVERSION An error occurred in a user supplied data conversion function
MPI_ERR_COUNT Invalid count argument
MPI_ERR_DIMS Invalid dimension argument
MPI_ERR_DISP Invalid displacement argument
MPI_ERR_DUP_DATAREP Conversion functions could not be registered because a data representation identifier that was already defined was passed to MPI_REGISTER_DATAREP
MPI_ERR_ERRHANDLER Invalid error handler argument
MPI_ERR_FILE Invalid file handle argument
MPI_ERR_FILE_IN_USE File operation could not be completed, as the file is currently open by some process
MPI_ERR_GROUP Invalid group argument
MPI_ERR_INFO Invalid info argument
MPI_ERR_IN_STATUS Error code is in status
MPI_ERR_INTERN Internal MPI (implementation) error
MPI_ERR_IO Other I/O error
MPI_ERR_KEYVAL Invalid keyval argument
MPI_ERR_LOCKTYPE Invalid locktype argument
MPI_ERR_NAME Invalid service name passed to MPI_LOOKUP_NAME
MPI_ERR_NO_MEM MPI_ALLOC_MEM failed because memory is exhausted
MPI_ERR_NO_SPACE Not enough space
MPI_ERR_NO_SUCH_FILE File does not exist


Collective argument not identical on all processes, or collective routines called in a different order by different processes

Table 8: Error classes (Part 2)

MPI_ERR_OP Invalid operation argument
MPI_ERR_OTHER Known error not in this list
MPI_ERR_PENDING Pending request
MPI_ERR_PORT Invalid port name passed to MPI_COMM_CONNECT
MPI_ERR_PROC_ABORTED Operation failed because a peer process has aborted
MPI_ERR_QUOTA Quota exceeded
MPI_ERR_RANK Invalid rank argument
MPI_ERR_READ_ONLY Read-only file or file system
MPI_ERR_REQUEST Invalid request argument
MPI_ERR_RMA_ATTACH Memory cannot be attached (e.g., because of resource exhaustion)
MPI_ERR_RMA_CONFLICT Conflicting accesses to window
MPI_ERR_RMA_FLAVOR Passed window has the wrong flavor for the called function
MPI_ERR_RMA_RANGE Target memory is not part of the window (in the case of a window created with MPI_WIN_CREATE_DYNAMIC, target memory is not attached)
MPI_ERR_RMA_SHARED Memory cannot be shared (e.g., some process in the group of the specified communicator cannot expose shared memory)
MPI_ERR_RMA_SYNC Wrong synchronization of RMA calls
MPI_ERR_ROOT Invalid root argument
MPI_ERR_SERVICE Invalid service name passed to MPI_UNPUBLISH_NAME
MPI_ERR_SESSION Invalid session argument
MPI_ERR_SIZE Invalid size argument
MPI_ERR_SPAWN Error in spawning processes
MPI_ERR_TAG Invalid tag argument
MPI_ERR_TOPOLOGY Invalid topology argument
MPI_ERR_TRUNCATE Message truncated on receive
MPI_ERR_TYPE Invalid datatype argument
MPI_ERR_UNKNOWN Unknown error
MPI_ERR_UNSUPPORTED_OPERATION Unsupported operation, such as seeking on a file that supports sequential access only
MPI_ERR_VALUE_TOO_LARGE Value is too large to store
MPI_ERR_WIN Invalid window argument
MPI_ERR_LASTCODE Last error code

The error classes are a subset of the error codes: an MPI function may return an error class number; and the function MPI_ERROR_STRING can be used to compute the error string associated with an error class. The values defined for MPI error classes are valid MPI error codes.

The error codes satisfy,

0 = errorMPI_SUCCESS < errorskipMPI_ERR_... ≥ errorMPI_ERR_LASTCODE.


The difference between MPI_ERR_UNKNOWN and MPI_ERR_OTHER is that MPI_ERROR_STRING can return useful information about MPI_ERR_OTHER.

Note that MPI_SUCCESS = 0 is necessary to be consistent with C practice; the separation of error classes and error codes allows us to define the error classes this way. Having a known LASTCODE is often a nice sanity check as well. ( End of rationale.)

Advice to implementors.

Note that all MPI_T_ return codes, which must have the prefix MPI_T_ERR_, are also required to satisfy

0 = mpiconstMPI_SUCCESS < constskipMPI_T_ERR_XXX/ ≥ mpiconstMPI_ERR_LASTCODE.

as described in Section Return Codes for the MPI Tool Information Interface. ( End of advice to implementors.)

MPI_ERROR_CLASS(errorcode, errorclass)
IN errorcodeError code returned by an MPI routine
OUT errorclassError class associated with errorcode
C binding
int MPI_Error_class(int errorcode, int *errorclass)
Fortran 2008 binding
MPI_Error_class(errorcode, errorclass, ierror)

INTEGER, INTENT(IN) :: errorcode
INTEGER, INTENT(OUT) :: errorclass
Fortran binding


The function MPI_ERROR_CLASS maps each standard error code (error class) onto itself.

This function must always be thread-safe, as defined in Section MPI and Threads. It is one of the few routines that may be called before MPI is initialized or after MPI is finalized.

Up: MPI Environmental Management Next: Error Classes, Error Codes, and Error Handlers Previous: Freeing Errorhandlers and Retrieving Error Strings

Return to MPI-4.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-4.1 of November 2, 2023
HTML Generated on November 19, 2023