VkResult(3)

C Specification

While the core Vulkan API is not designed to capture incorrect usage, some circumstances still require return codes. Commands in Vulkan return their status via return codes that are in one of two categories:

Successful completion codes are returned when a command needs to communicate success or status information. All successful completion codes are non-negative values.
Runtime error codes are returned when a command needs to communicate a failure that could only be detected at runtime. All runtime error codes are negative values.

All return codes in Vulkan are reported via VkResult return values. The possible codes are:

// Provided by VK_VERSION_1_0
typedef enum VkResult {
    VK_SUCCESS = 0,
    VK_NOT_READY = 1,
    VK_TIMEOUT = 2,
    VK_EVENT_SET = 3,
    VK_EVENT_RESET = 4,
    VK_INCOMPLETE = 5,
    VK_ERROR_OUT_OF_HOST_MEMORY = -1,
    VK_ERROR_OUT_OF_DEVICE_MEMORY = -2,
    VK_ERROR_INITIALIZATION_FAILED = -3,
    VK_ERROR_DEVICE_LOST = -4,
    VK_ERROR_MEMORY_MAP_FAILED = -5,
    VK_ERROR_LAYER_NOT_PRESENT = -6,
    VK_ERROR_EXTENSION_NOT_PRESENT = -7,
    VK_ERROR_FEATURE_NOT_PRESENT = -8,
    VK_ERROR_INCOMPATIBLE_DRIVER = -9,
    VK_ERROR_TOO_MANY_OBJECTS = -10,
    VK_ERROR_FORMAT_NOT_SUPPORTED = -11,
    VK_ERROR_FRAGMENTED_POOL = -12,
    VK_ERROR_UNKNOWN = -13,
  // Provided by VK_VERSION_1_1
    VK_ERROR_OUT_OF_POOL_MEMORY = -1000069000,
  // Provided by VK_VERSION_1_1
    VK_ERROR_INVALID_EXTERNAL_HANDLE = -1000072003,
  // Provided by VK_VERSION_1_2
    VK_ERROR_FRAGMENTATION = -1000161000,
  // Provided by VK_VERSION_1_2
    VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS = -1000257000,
    VK_ERROR_NOT_PERMITTED = -1000174001,
  // Provided by VKSC_VERSION_1_0
    VK_ERROR_VALIDATION_FAILED = -1000011001,
  // Provided by VKSC_VERSION_1_0
    VK_ERROR_INVALID_PIPELINE_CACHE_DATA = -1000298000,
  // Provided by VKSC_VERSION_1_0
    VK_ERROR_NO_PIPELINE_MATCH = -1000298001,
  // Provided by VK_KHR_surface
    VK_ERROR_SURFACE_LOST_KHR = -1000000000,
  // Provided by VK_KHR_surface
    VK_ERROR_NATIVE_WINDOW_IN_USE_KHR = -1000000001,
  // Provided by VK_KHR_swapchain
    VK_SUBOPTIMAL_KHR = 1000001003,
  // Provided by VK_KHR_swapchain
    VK_ERROR_OUT_OF_DATE_KHR = -1000001004,
  // Provided by VK_KHR_display_swapchain
    VK_ERROR_INCOMPATIBLE_DISPLAY_KHR = -1000003001,
  // Provided by VK_EXT_image_drm_format_modifier
    VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT = -1000158000,
  // Provided by VK_KHR_global_priority
    VK_ERROR_NOT_PERMITTED_KHR = VK_ERROR_NOT_PERMITTED,
} VkResult;

Description

Success Codes

VK_SUCCESS Command successfully completed
VK_NOT_READY A fence or query has not yet completed
VK_TIMEOUT A wait operation has not completed in the specified time
VK_EVENT_SET An event is signaled
VK_EVENT_RESET An event is unsignaled
VK_INCOMPLETE A return array was too small for the result
VK_SUBOPTIMAL_KHR A swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.

Error Codes

VK_ERROR_OUT_OF_HOST_MEMORY A host memory allocation has failed.
VK_ERROR_OUT_OF_DEVICE_MEMORY A device memory allocation has failed.
VK_ERROR_INITIALIZATION_FAILED Initialization of an object could not be completed for implementation-specific reasons.
VK_ERROR_DEVICE_LOST The logical or physical device has been lost. See Lost Device
VK_ERROR_MEMORY_MAP_FAILED Mapping of a memory object has failed.
VK_ERROR_LAYER_NOT_PRESENT A requested layer is not present or could not be loaded.
VK_ERROR_EXTENSION_NOT_PRESENT A requested extension is not supported.
VK_ERROR_FEATURE_NOT_PRESENT A requested feature is not supported.
VK_ERROR_INCOMPATIBLE_DRIVER The requested version of Vulkan is not supported by the driver or is otherwise incompatible for implementation-specific reasons.
VK_ERROR_TOO_MANY_OBJECTS Too many objects of the type have already been created.
VK_ERROR_FORMAT_NOT_SUPPORTED A requested format is not supported on this device.
VK_ERROR_FRAGMENTED_POOL A pool allocation has failed due to fragmentation of the pool’s memory. This must only be returned if no attempt to allocate host or device memory was made to accommodate the new allocation. This should be returned in preference to VK_ERROR_OUT_OF_POOL_MEMORY, but only if the implementation is certain that the pool allocation failure was due to fragmentation.
VK_ERROR_SURFACE_LOST_KHR A surface is no longer available.
VK_ERROR_NATIVE_WINDOW_IN_USE_KHR The requested window is already in use by Vulkan or another API in a manner which prevents it from being used again.
VK_ERROR_OUT_OF_DATE_KHR A surface has changed in such a way that it is no longer compatible with the swapchain, and further presentation requests using the swapchain will fail. Applications must query the new surface properties and recreate their swapchain if they wish to continue presenting to the surface.
VK_ERROR_INCOMPATIBLE_DISPLAY_KHR The display used by a swapchain does not use the same presentable image layout, or is incompatible in a way that prevents sharing an image.
VK_ERROR_OUT_OF_POOL_MEMORY A pool memory allocation has failed. This must only be returned if no attempt to allocate host or device memory was made to accommodate the new allocation. If the failure was definitely due to fragmentation of the pool, VK_ERROR_FRAGMENTED_POOL should be returned instead.
VK_ERROR_INVALID_EXTERNAL_HANDLE An external handle is not a valid handle of the specified type.
VK_ERROR_FRAGMENTATION A descriptor pool creation has failed due to fragmentation.
VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS A buffer creation or memory allocation failed because the requested address is not available.
VK_ERROR_VALIDATION_FAILED A command failed because invalid usage was detected by the implementation or a validation-layer.
VK_ERROR_INVALID_PIPELINE_CACHE_DATA The supplied pipeline cache data was not valid for the current implementation.
VK_ERROR_NO_PIPELINE_MATCH The implementation did not find a match in the pipeline cache for the specified pipeline, or VkPipelineOfflineCreateInfo was not provided to the vkCreate*Pipelines function.
VK_ERROR_NOT_PERMITTED The driver implementation has denied a request to acquire a priority above the default priority (VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) because the application does not have sufficient privileges.
VK_ERROR_UNKNOWN An unknown error has occurred; either the application has provided invalid input, or an implementation failure has occurred.

If a command returns a runtime error, unless otherwise specified any output parameters will have undefined contents, except that if the output parameter is a structure with sType and pNext fields, those fields will be unmodified. Any structures chained from pNext will also have undefined contents, except that sType and pNext will be unmodified.

VK_ERROR_OUT_OF_*_MEMORY errors do not modify any currently existing Vulkan objects. Objects that have already been successfully created can still be used by the application. If VkPhysicalDeviceVulkanSC10Properties::deviceNoDynamicHostAllocations is VK_TRUE, VK_ERROR_OUT_OF_HOST_MEMORY must not be returned from any physical or logical device command which explicitly disallows it.

Note	As a general rule, `Free`, `Release`, and `Reset` commands do not return `VK_ERROR_OUT_OF_HOST_MEMORY`, while any other command with a return code may return it. Any exceptions from this rule are described for those commands.

VK_ERROR_UNKNOWN will be returned by an implementation when an unexpected error occurs that cannot be attributed to valid behavior of the application and implementation. Under these conditions, it may be returned from any command returning a VkResult.

Note

VK_ERROR_UNKNOWN is not expected to ever be returned if the application behavior is valid, and if the implementation is bug-free. If VK_ERROR_UNKNOWN is received, the application should be checked against the latest validation layers to verify correct behavior as much as possible. If no issues are identified it could be an implementation issue, and the implementor should be contacted for support.

Any command returning a VkResult may return VK_ERROR_VALIDATION_FAILED if a violation of valid usage is detected, even though commands do not explicitly list this as a possible return code.

Performance-critical commands generally do not have return codes. If a runtime error occurs in such commands, the implementation will defer reporting the error until a specified point. For commands that record into command buffers (vkCmd*) runtime errors are reported by vkEndCommandBuffer.

Note	Implementations can also use https://registry.khronos.org/vulkansc/specs/1.0-extensions/html/vkspec.html#fault-handling to report runtime errors where suitable return values are not available or to provide more prompt notification of an error.

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

SPDX-License-Identifier: CC-BY-4.0

VkResult(3) Manual Page

Name

C Specification

Description

See Also

Document Notes

Copyright