1# Errors
2
3This describes the set of userspace-exposed errors used in Zircon. The first section provides the
4canonical names and description of each error code. The second section provides the concrete values.
5
6Within the kernel, errors are typically resulted as variables of type `status_t` and errors are
7defined by macros of the form `ZX_ERR_CANONICAL_NAME` e.g. `ZX_ERR_INTERNAL`. All error cases are negative
8values and success is represented by a non-negative value.
9
10In userspace the syscall dispatch layer (libzircon) exposes the result values as variables of type
11`zx_status_t` that currently use the same spelling and values as the kernel for errors, but which
12will transition to using 0 for success and positive values for errors.
13
14See [Kernel internal errors](kernel_internal_errors.md) for a list of kernel-internal values.
15
16## Descriptions
17
18Each category represents a class of errors. The first error code in each category is the generic
19code for that category and is used when no more specific code applies. Further error codes (if any)
20within a category represent particular types of errors within the class. In general, more specific
21error codes are preferred where possible.
22
23Errors are described in terms of an operation, arguments, a subject, and identifiers. An operation
24is typically a function or system call. Arguments are typically the parameters to the call. The
25subject of an operation is the primary object the operation acts on, typically a handle and
26typically passed as the first argument. Identifiers are typically numbers or strings intended to
27unambiguously identify a resource used in the operation.
28
29## Categories
30
31### Success
32**ZX\_OK**
33 Operation succeeded.
34
35### General errors
36
37These indicate that the system hit a general error while attempting the operation.
38
39**INTERNAL**
40  The system encountered an otherwise unspecified error while performing the operation.
41
42**NOT\_SUPPORTED**
43  The operation is not supported, implemented, or enabled.
44
45**NO\_RESOURCES**
46  The system was not able to allocate some resource needed for the operation.
47
48**NO\_MEMORY**
49  The system was not able to allocate memory needed for the operation.
50
51### Parameter errors
52
53These indicate that the caller specified a parameter that does not specify a valid operation or that
54is invalid for the specified operation.
55
56**INVALID\_ARGUMENT**
57  An argument is invalid.
58
59**WRONG\_TYPE**
60  The subject of the operation is the wrong type to perform the operation.
61  Example: Attempting a message\_read on a thread handle.
62
63**BAD\_SYSCALL**
64  The specified syscall number is invalid.
65
66**BAD\_HANDLE**
67  A specified handle value does not refer to a handle.
68
69**OUT\_OF\_RANGE**
70  An argument is outside the valid range for this operation.
71   Note: This is used when the argument may be valid if the system changes state, unlike
72    INVALID\_ARGUMENT which is used when the argument will never be valid.
73
74**BUFFER\_TOO\_SMALL**
75  A caller provided buffer is too small for this operation.
76
77### Precondition or state errors
78
79These indicate that the operation could not succeed because the preconditions for the operation are
80not satisfied or the system is unable to complete the operation in its current state.
81
82**BAD\_STATE**
83  The system is unable to perform the operation in its current state.
84   Note: FAILED\_PRECONDITION is a reserved alias for this error
85
86**NOT\_FOUND**
87  The requested entity was not found.
88
89**TIMED\_OUT**
90  The time limit for the operation elapsed before the operation completed.
91
92**ALREADY\_EXISTS**
93  An object with the specified identifier already exists.
94  Example: Attempting to create a file when a file already exists with that name.
95
96**ALREADY\_BOUND**
97  The operation failed because the named entity is already owned or controlled by another entity.
98  The operation could succeed later if the current owner releases the entity.
99
100**HANDLE\_CLOSED**
101  A handle being waited on was closed.
102
103**REMOTE\_CLOSED**
104  The operation failed because the remote end of the subject of the operation was closed.
105
106**UNAVAILABLE**
107  The subject of the operation is currently unable to perform the operation.
108  Note: This is used when there's no direct way for the caller to observe when the subject will be
109  able to perform the operation and should thus retry.
110
111**SHOULD\_WAIT**
112  The operation cannot be performed currently but potentially could succeed if the caller waits for
113  a prerequisite to be satisfied, for example waiting for a handle to be readable or writable.
114  Example: Attempting to read from a channel that has no messages waiting but has an open
115  remote will return **SHOULD\_WAIT**. Attempting to read from a channel that has no messages
116  waiting and has a closed remote end will return **REMOTE\_CLOSED**.
117
118### Permission errors
119
120**ACCESS\_DENIED**
121  The caller did not have permission to perform the specified operation.
122
123### Input/output errors
124
125**IO**
126  Otherwise unspecified error occurred during I/O.
127
128**IO\_REFUSED**
129  The entity the I/O operation is being performed on rejected the operation.
130  Example: an I2C device NAK'ing a transaction or a disk controller rejecting an invalid command.
131
132**IO\_DATA\_INTEGRITY**
133  The data in the operation failed an integrity check and is possibly corrupted.
134  Example: CRC or Parity error.
135
136**IO\_DATA\_LOSS**
137  The data in the operation is currently unavailable and may be permanently lost.
138  Example: A disk block is irrecoverably damaged.
139