api/appendix_f.asciidoc

// Copyright 2017-2024 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

[appendix]
[[error_codes]]
= Error Codes

This section lists OpenCL error codes and their meanings.

// Editors note: Other than CL_SUCCESS, please keep this table in alphabetical order!

[cols="2,3",options="header",]
|====
| *Error Code*
| *Brief Description*

| {CL_SUCCESS_anchor}

include::{generated}/api/version-notes/CL_SUCCESS.asciidoc[]
| This is a special error code to indicate that the API executed successfully, without errors.

| {CL_BUILD_PROGRAM_FAILURE_anchor}

include::{generated}/api/version-notes/CL_BUILD_PROGRAM_FAILURE.asciidoc[]
| Returned when {clBuildProgram} failed to build the specified program.

| {CL_COMPILE_PROGRAM_FAILURE_anchor}

include::{generated}/api/version-notes/CL_COMPILE_PROGRAM_FAILURE.asciidoc[]
| Returned when {clCompileProgram} failed to compile the specified program.

| {CL_COMPILER_NOT_AVAILABLE_anchor}

include::{generated}/api/version-notes/CL_COMPILER_NOT_AVAILABLE.asciidoc[]
| Returned when compiling or building a program from source or IL when {CL_DEVICE_COMPILER_AVAILABLE} is {CL_FALSE}.

| {CL_DEVICE_NOT_FOUND_anchor}

include::{generated}/api/version-notes/CL_DEVICE_NOT_FOUND.asciidoc[]
| Returned when no devices were found that match the specified device type.

| {CL_DEVICE_NOT_AVAILABLE_anchor}

include::{generated}/api/version-notes/CL_DEVICE_NOT_AVAILABLE.asciidoc[]
| Returned when attempting to use a device when {CL_DEVICE_AVAILABLE} is {CL_FALSE}.

| {CL_DEVICE_PARTITION_FAILED_anchor}

include::{generated}/api/version-notes/CL_DEVICE_PARTITION_FAILED.asciidoc[]
| Returned when device partitioning is supported but the device could not be further partitioned.

| {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST_anchor}

include::{generated}/api/version-notes/CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST.asciidoc[]
| Returned by blocking APIs when an event in the event wait list has a negative value, indicating it is in an error state.

| {CL_IMAGE_FORMAT_MISMATCH_anchor}

include::{generated}/api/version-notes/CL_IMAGE_FORMAT_MISMATCH.asciidoc[]
| Returned when attempting to copy images that do not use the same image format.

| {CL_IMAGE_FORMAT_NOT_SUPPORTED_anchor}

include::{generated}/api/version-notes/CL_IMAGE_FORMAT_NOT_SUPPORTED.asciidoc[]
| Returned when attempting to create or use an image format that is not supported.

| {CL_INVALID_ARG_INDEX_anchor}

include::{generated}/api/version-notes/CL_INVALID_ARG_INDEX.asciidoc[]
| Returned when attempting to get or set a kernel argument using an invalid index for the specified kernel.

| {CL_INVALID_ARG_SIZE_anchor}

include::{generated}/api/version-notes/CL_INVALID_ARG_SIZE.asciidoc[]
| Returned when the specified size of a kernel argument does not match the size of the kernel argument.

| {CL_INVALID_ARG_VALUE_anchor}

include::{generated}/api/version-notes/CL_INVALID_ARG_VALUE.asciidoc[]
| Returned when attempting to set a kernel argument that is not valid.

| {CL_INVALID_BINARY_anchor}

include::{generated}/api/version-notes/CL_INVALID_BINARY.asciidoc[]
| Returned when a program binary is not valid for a device.

| {CL_INVALID_BUFFER_SIZE_anchor}

include::{generated}/api/version-notes/CL_INVALID_BUFFER_SIZE.asciidoc[]
| Returned when attempting to create a buffer or a sub-buffer with an invalid size.

| {CL_INVALID_BUILD_OPTIONS_anchor}

include::{generated}/api/version-notes/CL_INVALID_BUILD_OPTIONS.asciidoc[]
| Returned when build options passed to {clBuildProgram} are not valid.

| {CL_INVALID_COMMAND_QUEUE_anchor}

include::{generated}/api/version-notes/CL_INVALID_COMMAND_QUEUE.asciidoc[]
| Returned when the specified command-queue is not a <<valid-object-definition,valid command-queue>>.

| {CL_INVALID_COMPILER_OPTIONS_anchor}

include::{generated}/api/version-notes/CL_INVALID_COMPILER_OPTIONS.asciidoc[]
| Returned when compiler options passed to {clCompileProgram} are not valid.

| {CL_INVALID_CONTEXT_anchor}

include::{generated}/api/version-notes/CL_INVALID_CONTEXT.asciidoc[]
| Returned when a specified context is not a <<valid-object-definition,valid context>>, or when mixing objects from multiple contexts.

| {CL_INVALID_DEVICE_anchor}

include::{generated}/api/version-notes/CL_INVALID_DEVICE.asciidoc[]
| Returned when a specified device is not a <<valid-object-definition,valid device>>.

| {CL_INVALID_DEVICE_PARTITION_COUNT_anchor}

include::{generated}/api/version-notes/CL_INVALID_DEVICE_PARTITION_COUNT.asciidoc[]
| Returned when the requested device partitioning using {CL_DEVICE_PARTITION_BY_COUNTS} is not valid.

| {CL_INVALID_DEVICE_QUEUE_anchor}

include::{generated}/api/version-notes/CL_INVALID_DEVICE_QUEUE.asciidoc[]
| Returned when setting a device queue kernel argument to a value that is not a valid device command-queue.

| {CL_INVALID_DEVICE_TYPE_anchor}

include::{generated}/api/version-notes/CL_INVALID_DEVICE_TYPE.asciidoc[]
| Returned when the requested device type is not a valid value.

| {CL_INVALID_EVENT_anchor}

include::{generated}/api/version-notes/CL_INVALID_EVENT.asciidoc[]
| Returned when a specified event object is not a <<valid-object-definition,valid event object>>.

| {CL_INVALID_EVENT_WAIT_LIST_anchor}

include::{generated}/api/version-notes/CL_INVALID_EVENT_WAIT_LIST.asciidoc[]
| Returned when the specified event wait list or number of events in the wait list is not valid.

// This is currently defined in cl.h, but it's not a core API error code.
//| {CL_INVALID_GL_OBJECT_anchor}
//
//include::{generated}/api/version-notes/CL_INVALID_GL_OBJECT.asciidoc[]
//|

| {CL_INVALID_GLOBAL_OFFSET_anchor}

include::{generated}/api/version-notes/CL_INVALID_GLOBAL_OFFSET.asciidoc[]
| Returned when the specified global offset and global work size exceeds the limits of the device.

| {CL_INVALID_GLOBAL_WORK_SIZE_anchor}

include::{generated}/api/version-notes/CL_INVALID_GLOBAL_WORK_SIZE.asciidoc[]
| Returned when the specified global work size exceeds the limits of the device.

| {CL_INVALID_HOST_PTR_anchor}

include::{generated}/api/version-notes/CL_INVALID_HOST_PTR.asciidoc[]
| Returned when the specified host pointer is not valid for the specified flags.

| {CL_INVALID_IMAGE_DESCRIPTOR_anchor}

include::{generated}/api/version-notes/CL_INVALID_IMAGE_DESCRIPTOR.asciidoc[]
| Returned when the specified image descriptor is `NULL` or specifies invalid values.

| {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR_anchor}

include::{generated}/api/version-notes/CL_INVALID_IMAGE_FORMAT_DESCRIPTOR.asciidoc[]
| Returned when the specified image format descriptor is `NULL` or specifies invalid value.

| {CL_INVALID_IMAGE_SIZE_anchor}

include::{generated}/api/version-notes/CL_INVALID_IMAGE_SIZE.asciidoc[]
| Returned when the specified image dimensions exceed the maximum dimensions for a device or all devices in a context.

| {CL_INVALID_KERNEL_anchor}

include::{generated}/api/version-notes/CL_INVALID_KERNEL.asciidoc[]
| Returned when the specified kernel is not a <<valid-object-definition,valid kernel object>>.

| {CL_INVALID_KERNEL_ARGS_anchor}

include::{generated}/api/version-notes/CL_INVALID_KERNEL_ARGS.asciidoc[]
| Returned when enqueing a kernel when some kernel arguments have not been set or are invalid.

| {CL_INVALID_KERNEL_DEFINITION_anchor}

include::{generated}/api/version-notes/CL_INVALID_KERNEL_DEFINITION.asciidoc[]
| Returned when creating a kernel for multiple devices where the number of kernel arguments or kernel argument types are not the same for all devices.

| {CL_INVALID_KERNEL_NAME_anchor}

include::{generated}/api/version-notes/CL_INVALID_KERNEL_NAME.asciidoc[]
| Returned when creating a kernel when no kernel with the specified name exists in the program object.

| {CL_INVALID_LINKER_OPTIONS_anchor}

include::{generated}/api/version-notes/CL_INVALID_LINKER_OPTIONS.asciidoc[]
| Returned when build options passed to {clLinkProgram} are not valid.

| {CL_INVALID_MEM_OBJECT_anchor}

include::{generated}/api/version-notes/CL_INVALID_MEM_OBJECT.asciidoc[]
| Returned when a specified memory object is not a <<valid-object-definition,valid memory object>>.

// This currently defined in cl.h, but it's not a core API error code.
//| {CL_INVALID_MIP_LEVEL_anchor}
//
//include::{generated}/api/version-notes/CL_INVALID_MIP_LEVEL.asciidoc[]
//|

| {CL_INVALID_OPERATION_anchor}

include::{generated}/api/version-notes/CL_INVALID_OPERATION.asciidoc[]
| This is a generic error code that is returned when the requested operation is not a valid operation.

| {CL_INVALID_PIPE_SIZE_anchor}

include::{generated}/api/version-notes/CL_INVALID_PIPE_SIZE.asciidoc[]
| Returned when attempting to create a pipe with an invalid packet size or number of packets.

| {CL_INVALID_PLATFORM_anchor}

include::{generated}/api/version-notes/CL_INVALID_PLATFORM.asciidoc[]
| Returned when the specified platform is not a <<valid-object-definition,valid platform>>.

| {CL_INVALID_PROGRAM_anchor}

include::{generated}/api/version-notes/CL_INVALID_PROGRAM.asciidoc[]
| Returned when a specified program is not a <<valid-object-definition,valid program object>>.

| {CL_INVALID_PROGRAM_EXECUTABLE_anchor}

include::{generated}/api/version-notes/CL_INVALID_PROGRAM_EXECUTABLE.asciidoc[]
| Returned when the specified program is valid but has not been successfully built.

| {CL_INVALID_PROPERTY_anchor}

include::{generated}/api/version-notes/CL_INVALID_PROPERTY.asciidoc[]
| Returned when a specified property name is invalid, when the value for a property name is invalid, or when the same property name is specified more than once.

| {CL_INVALID_QUEUE_PROPERTIES_anchor}

include::{generated}/api/version-notes/CL_INVALID_QUEUE_PROPERTIES.asciidoc[]
| Returned when specified queue properties are valid but are not supported by the device.

| {CL_INVALID_SAMPLER_anchor}

include::{generated}/api/version-notes/CL_INVALID_SAMPLER.asciidoc[]
| Returned when a specified sampler is not a <<valid-object-definition,valid sampler object>>.

| {CL_INVALID_SPEC_ID_anchor}

include::{generated}/api/version-notes/CL_INVALID_SPEC_ID.asciidoc[]
| Returned when the specified specialization constant ID is not valid for the specified program.

| {CL_INVALID_VALUE_anchor}

include::{generated}/api/version-notes/CL_INVALID_VALUE.asciidoc[]
| This is a generic error that is returned when a specified value is not a valid value.

| {CL_INVALID_WORK_DIMENSION_anchor}

include::{generated}/api/version-notes/CL_INVALID_WORK_DIMENSION.asciidoc[]
| Returned by {clEnqueueNDRangeKernel} when the specified work dimension is not valid.

| {CL_INVALID_WORK_GROUP_SIZE_anchor}

include::{generated}/api/version-notes/CL_INVALID_WORK_GROUP_SIZE.asciidoc[]
| Returned by {clEnqueueNDRangeKernel} when the specified total work-group size is not valid for the specified kernel or device.

// This is a strange error code - replace by CL_INVALID_WORK_GROUP_SIZE?
| {CL_INVALID_WORK_ITEM_SIZE_anchor}

include::{generated}/api/version-notes/CL_INVALID_WORK_ITEM_SIZE.asciidoc[]
| Returned by {clEnqueueNDRangeKernel} when the specified work-group size in one dimension is not valid for the device.

| {CL_KERNEL_ARG_INFO_NOT_AVAILABLE_anchor}

include::{generated}/api/version-notes/CL_KERNEL_ARG_INFO_NOT_AVAILABLE.asciidoc[]
| Returned by {clGetKernelArgInfo} when kernel argument information is not available for the specified kernel.

| {CL_LINK_PROGRAM_FAILURE_anchor}

include::{generated}/api/version-notes/CL_LINK_PROGRAM_FAILURE.asciidoc[]
| Returned by {clLinkProgram} when there is a failure to link the specified binaries or libraries.

| {CL_LINKER_NOT_AVAILABLE_anchor}

include::{generated}/api/version-notes/CL_LINKER_NOT_AVAILABLE.asciidoc[]
| Returned by {clLinkProgram} when {CL_DEVICE_LINKER_AVAILABLE} is {CL_FALSE}.

| {CL_MAP_FAILURE_anchor}

include::{generated}/api/version-notes/CL_MAP_FAILURE.asciidoc[]
| Returned when there is a failure to map the specified region into the host address space.

| {CL_MEM_COPY_OVERLAP_anchor}

include::{generated}/api/version-notes/CL_MEM_COPY_OVERLAP.asciidoc[]
| Returned when copying from one region of a memory object to another where the source and destination regions overlap.

| {CL_MEM_OBJECT_ALLOCATION_FAILURE_anchor}

include::{generated}/api/version-notes/CL_MEM_OBJECT_ALLOCATION_FAILURE.asciidoc[]
| Returned when there is a failure to allocate memory for a memory object.

| {CL_MISALIGNED_SUB_BUFFER_OFFSET_anchor}

include::{generated}/api/version-notes/CL_MISALIGNED_SUB_BUFFER_OFFSET.asciidoc[]
| Returned when a sub-buffer object is created or used that is not aligned to {CL_DEVICE_MEM_BASE_ADDR_ALIGN} for the device.

| {CL_OUT_OF_HOST_MEMORY_anchor}

include::{generated}/api/version-notes/CL_OUT_OF_HOST_MEMORY.asciidoc[]
| This is a generic error that is returned when memory could not be allocated on the host.

| {CL_OUT_OF_RESOURCES_anchor}

include::{generated}/api/version-notes/CL_OUT_OF_RESOURCES.asciidoc[]
| This is a generic error that is returned when resources could not be allocated on the device.

| {CL_MAX_SIZE_RESTRICTION_EXCEEDED_anchor}

include::{generated}/api/version-notes/CL_MAX_SIZE_RESTRICTION_EXCEEDED.asciidoc[]
| Returned when the size of the specified kernel argument value exceeds the maximum size defined for the kernel argument.

| {CL_PROFILING_INFO_NOT_AVAILABLE_anchor}

include::{generated}/api/version-notes/CL_PROFILING_INFO_NOT_AVAILABLE.asciidoc[]
| Returned by {clGetEventProfilingInfo} when the command associated with the specified event was not enqueued into a command-queue with {CL_QUEUE_PROFILING_ENABLE}.

ifdef::cl_khr_icd[]
| {CL_PLATFORM_NOT_FOUND_KHR_anchor}

include::{generated}/api/version-notes/CL_PLATFORM_NOT_FOUND_KHR.asciidoc[]
  | Returned by {clGetPlatformIDs} when no platforms are available.
endif::cl_khr_icd[]

|====