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_SUCCESS | No error |
| 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_EXISTS | File exists |
| 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_INFO_KEY | Key longer than MPI_MAX_INFO_KEY |
| MPI_ERR_INFO_NOKEY | Invalid key passed to MPI_INFO_DELETE |
| MPI_ERR_INFO_VALUE | Value longer than MPI_MAX_INFO_VAL |
| 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 |
|
MPI_ERR_NOT_SAME | Collective argument not identical on
all processes, or collective routines
called in a different order by
different processes
|
| 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_DATAREP | Unsupported datarep passed to MPI_FILE_SET_VIEW |
| 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 codes satisfy,
0 = errorMPI_SUCCESS < errorskipMPI_ERR_... ≥ errorMPI_ERR_LASTCODE.
Rationale.
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 errorcode | Error code returned by an MPI routine |
| OUT errorclass | Error class associated with errorcode |
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.