Vulkan Loader and Installable Client Driver (ICD) Compatibility Handshake

Direct answer

The Vulkan loader, not the ICD, is authoritative for the compatibility check that produces VK_ERROR_INCOMPATIBLE_DRIVER. During vkCreateInstance, the loader discovers ICDs through platform-specific manifests, loads each library, and negotiates the loader/ICD interface version with vk_icdNegotiateLoaderICDInterfaceVersion. If no ICD completes the handshake, the loader returns the error from vkCreateInstance. The ICD only responds to the negotiation; it does not decide whether the loader accepts it.

What the API can and cannot distinguish

Vulkan provides no standardized in-API method to separate a permanent driver mismatch from a transient initialization failure. VK_ERROR_INCOMPATIBLE_DRIVER is terminal for that call, and the API exposes no query for a compatible loader/ICD version or an automatic fallback path. Retrying the same call is the only in-API action, and it will not repair a missing manifest, a library locked during a partial update, or an ICD with an obsolete loader interface.

Confirmed behavior versus likely explanation

Item	Status	Notes
Loader enforces the compatibility check	Confirmed	Loader performs ICD discovery and interface-version negotiation.
ICD decides compatibility	Not supported	ICD responds to negotiation; loader makes the skip or error decision.
In-API distinction permanent vs transient	Not available	No Vulkan query separates these states.
Transient failures surface as VK_ERROR_INITIALIZATION_FAILED	Likely	Common in practice, but not a guaranteed diagnostic signal.

Verification steps for this case

1. Set VK_LOADER_DEBUG=all and rerun instance creation. Check which ICDs are discovered and whether interface-version negotiation fails.
2. Confirm the ICD manifest (Linux: /usr/share/vulkan/icd.d/*.json) or Windows registry entry points to an existing library exporting vk_icdNegotiateLoaderICDInterfaceVersion and vk_icdGetInstanceProcAddr.
3. Compare the negotiated loader/ICD interface version in the debug log against the versions supported by the installed loader and driver packages.

Version assumption

This behavior assumes a standard loader implementing the loader/ICD interface-version negotiation. That interface version is distinct from the Vulkan API version; a driver can advertise a modern Vulkan API version yet fail the handshake if its loader interface is too old. A newer loader may reject an older ICD that previously worked, which is why partial updates are a common trigger.

Missing diagnostic detail

Confirm whether VK_ERROR_INCOMPATIBLE_DRIVER is returned by vkCreateInstance or vkCreateDevice. The loader handshake occurs during instance creation. If the error appears at vkCreateDevice, the loader already selected an ICD, so the cause is likely ICD-specific device creation rather than a loader/ICD compatibility mismatch.