This describes the set of userspace-exposed errors used in Zircon. The first section provides the canonical names and description of each error code. The second section provides the concrete values.
Within the kernel, errors are typically resulted as variables of type status_t and errors are
defined by macros of the form ZX_ERR_CANONICAL_NAME e.g. ZX_ERR_INTERNAL. All error cases are negative
values and success is represented by a non-negative value.
In userspace the syscall dispatch layer (libzircon) exposes the result values as variables of type
zx_status_t that currently use the same spelling and values as the kernel for errors, but which
will transition to using 0 for success and positive values for errors.
See Kernel internal errors for a list of kernel-internal values.
Descriptions
Each category represents a class of errors. The first error code in each category is the generic code for that category and is used when no more specific code applies. Further error codes (if any) within a category represent particular types of errors within the class. In general, more specific error codes are preferred where possible.
Errors are described in terms of an operation, arguments, a subject, and identifiers. An operation is typically a function or system call. Arguments are typically the parameters to the call. The subject of an operation is the primary object the operation acts on, typically a handle and typically passed as the first argument. Identifiers are typically numbers or strings intended to unambiguously identify a resource used in the operation.
Categories
Success
ZX_OK Operation succeeded.
General errors
These indicate that the system hit a general error while attempting the operation.
INTERNAL The system encountered an otherwise unspecified error while performing the operation.
NOT_SUPPORTED The operation is not supported, implemented, or enabled.
NO_RESOURCES The system was not able to allocate some resource needed for the operation.
NO_MEMORY The system was not able to allocate memory needed for the operation.
Parameter errors
These indicate that the caller specified a parameter that does not specify a valid operation or that is invalid for the specified operation.
INVALID_ARGUMENT An argument is invalid.
WRONG_TYPE The subject of the operation is the wrong type to perform the operation. Example: Attempting a message_read on a thread handle.
BAD_SYSCALL The specified syscall number is invalid.
BAD_HANDLE A specified handle value does not refer to a handle.
OUT_OF_RANGE An argument is outside the valid range for this operation. Note: This is used when the argument may be valid if the system changes state, unlike INVALID_ARGUMENT which is used when the argument will never be valid.
BUFFER_TOO_SMALL A caller provided buffer is too small for this operation.
Precondition or state errors
These indicate that the operation could not succeed because the preconditions for the operation are not satisfied or the system is unable to complete the operation in its current state.
BAD_STATE The system is unable to perform the operation in its current state. Note: FAILED_PRECONDITION is a reserved alias for this error
NOT_FOUND The requested entity was not found.
TIMED_OUT The time limit for the operation elapsed before the operation completed.
ALREADY_EXISTS An object with the specified identifier already exists. Example: Attempting to create a file when a file already exists with that name.
ALREADY_BOUND The operation failed because the named entity is already owned or controlled by another entity. The operation could succeed later if the current owner releases the entity.
HANDLE_CLOSED A handle being waited on was closed.
PEER_CLOSED The operation failed because the remote end of the subject of the operation was closed.
UNAVAILABLE The subject of the operation is currently unable to perform the operation. Note: This is used when there's no direct way for the caller to observe when the subject will be able to perform the operation and should thus retry.
SHOULD_WAIT The operation cannot be performed currently but potentially could succeed if the caller waits for a prerequisite to be satisfied, for example waiting for a handle to be readable or writable. Example: Attempting to read from a channel that has no messages waiting but has an open remote will return SHOULD_WAIT. Attempting to read from a channel that has no messages waiting and has a closed remote end will return PEER_CLOSED.
Permission errors
ACCESS_DENIED The caller did not have permission to perform the specified operation.
Input/output errors
IO Otherwise unspecified error occurred during I/O.
IO_REFUSED The entity the I/O operation is being performed on rejected the operation. Example: an I2C device NAK'ing a transaction or a disk controller rejecting an invalid command.
IO_DATA_INTEGRITY The data in the operation failed an integrity check and is possibly corrupted. Example: CRC or Parity error.
IO_DATA_LOSS The data in the operation is currently unavailable and may be permanently lost. Example: A disk block is irrecoverably damaged.