VkPipelineCache data invalidation after driver updates

Short answer

Drivers decide cache staleness by checking the values stored in the cache header against the current device state. If any of those values differ, the driver silently discards the cache and recompiles the pipeline. There is no standard API to report whether the cache was actually used.

Detailed explanation

What the driver looks at

• API version – the apiVersion field in the cache header must match the device’s apiVersion returned by vkGetPhysicalDeviceProperties2.
• Driver version – the driverVersion field in the header must equal the current driver’s driverVersion (or fall within a vendor‑defined compatibility window). Many vendors bump this field with each major/minor update.
• Cache header version – the VkPipelineCacheHeaderVersion value (currently VK_PIPELINE_CACHE_HEADER_VERSION_ONE) must match. Vendors may introduce new header versions that carry additional data.
• Hardware identifiers – vendorID and deviceID are compared to ensure the cache was built for the same GPU.
• Feature set – if the device’s enabled features or extensions differ from those recorded during cache creation, the driver may treat the cache as incompatible.

When the cache is ignored

If any of the above checks fail, the driver silently drops the cache data and compiles the pipeline from scratch. The API does not expose a flag or return value that explicitly says “cache ignored.”

How to detect that it happened

1. Query the current driver state. Use vkGetPhysicalDeviceProperties2 to fetch apiVersion, driverVersion, and vendorID/deviceID.
2. Load the existing cache. Create a VkPipelineCache from the file data.
3. Attempt pipeline creation. Call vkCreateGraphicsPipelines with the cache attached.
4. Check the return code. Errors such as VK_ERROR_INVALID_SHADER_NV or VK_ERROR_OUT_OF_DEVICE_MEMORY usually indicate the cache was discarded. A successful return means the cache was accepted.
5. Inspect cache data after creation. Call vkGetPipelineCacheData. If the returned size is larger than the original, the driver has added data, suggesting the cache was used. If the size is unchanged or the data is identical, it may have been ignored.

Practical steps for a typical app

1. Store a version token. When you write the cache to disk, also write the driver’s driverVersion and apiVersion you used.
2. On startup, compare tokens. If the stored token differs from the current device, skip loading the cache entirely.
3. Fallback path. If you still want to try, load the cache and create pipelines as usual. If creation fails, delete the cache file and rebuild from scratch.
4. Optional vendor extension. Some vendors expose VkPhysicalDevicePipelineCacheCompatibilityProperties via an extension; you can query that to get a compatibility string. If present, compare it with the stored string.

What we still don’t know

Because the Vulkan spec leaves cache format entirely vendor‑specific, there is no universal way to ask the driver “Did you use this cache?” The only reliable signals are error codes and changes in cache size after pipeline creation.

Missing diagnostic detail

Did you observe any pipeline‑creation errors after updating the driver? If not, let us know so we can refine the recommendation.