Workarounds are fixes for features on a device that help you avoid device or driver issues and hardware quirks. The Workaround strings directly map to Boolean statements in the Vulkan back-end.
Unity’s Vulkan back-end includes built‑in device and driver workarounds that Unity applies automatically based on:
These decisions aren’t public and can favor compatibility over performance and aggressive feature usage.
Vulkan hardware profiles let you enable, disable, or keep these workarounds on targeted devices, which is useful because it gives you control when Unity’s automatic detection isn’t perfect or when you need different performance and accuracy trade‑offs on specific devices.
If you don’t configure any workarounds, the default behavior applies. Advanced controls let you tailor behavior for specific scenarios.
Use SetWorkaround to enable or disable a specific workaround:
public void SetWorkaround(string workaroundName, State state)
For example, the following code disables a workaround that can happen when vkGetPipelineCacheData reports or returns inconsistent sizes:
samsungProfile.SetWorkaround("HasBuggyPipelineCacheDataSize", State.Disabled);
Note: Unity validates workaround names at application startup. To view validation errors, build and run your application as a Development BuildA development build includes debug symbols and enables the Profiler. More info
See in Glossary, then check the logcat output.
For a list of possible workarounds you can toggle, refer to Workaround options.
The following table describes the driver behavior or rendering symptom that typically triggers each workaround. Use these workaround properties to enable or disable specific workarounds:
| Workaround option | Cause |
|---|---|
HasBuggyPipelineCacheDataSize |
vkGetPipelineCacheData reports or returns inconsistent sizes. |
HasBuggyPipelineCacheHeaderVersion |
Some drivers read/write an incorrect pipeline cache header version. |
HasBuggyBackBufferCopyImage |
Some drivers corrupt data or swizzle color channels when the application copies from a swapchain image or backbuffer image. |
HasBuggyRenderingWithoutFragmentShader |
Pipelines without a fragment shaderA program that runs on the GPU. More info See in Glossary might fail or render nothing. |
HasBuggyResetCommandBuffer |
The driver becomes unstable or crashes after the application resets a command buffer or command pool and then reuses it. |
HasBuggyCopyImageToBuffer |
vkCmdCopyImageToBuffer might ignore the specified offset, which can lead to misaligned copies. |
HasBuggyAutoResolveStoreResolvedOnly |
The driver produces artifacts when the application uses a resolve-only subpass and sets the multisampled attachment storeOp to DONT_CARE. |
HasBuggySubAllocatedColorAttachment |
Images bound with a non‑zero memory offset (sub-allocated) can corrupt when used as color attachments. |
HasBuggyRenderingWithColorMask0 |
Depth‑only pipelines or those with color write mask = 0 can trigger incorrect depth or early‑z behavior. |
HasBuggyLoadStoreAttachmentOps |
The driver doesn’t honor attachment load or store operations correctly when the application uses different values at frame buffer setup time and command recording time. |
HasBuggyBitfieldUExtract |
The unsigned bitfieldExtract operation can produce incorrect results in shaders. |
HasBuggyTransferExecutionDependencyChain |
Minimal (spec‑legal) synchronization for transfer operations might be insufficient, which can cause hazards. |
HasBuggySRGBSwapChain |
The driver handles sRGB swapchain formats incorrectly, which can produce incorrect gamma or color output. |
HasBuggyDescriptorSetUpdateTemplate |
Descriptor update templates might mishandle updates that span multiple consecutive bindings. |
HasBuggyDebugUtilsLabels |
The driver or tooling can crash when the application uses matching debug labels across command buffers or queues. |
HasBuggyMSAAResolvePass |
The driver skips a subpass when the application uses it only for MSAA resolve and records no other commands in that subpass. |
Use the following states to set the status of the workaround options:
| State | Description |
|---|---|
| Default | Let the system decide whether to apply the workaround. |
| Enabled | Enable a certain workaround on a device. |
| Disabled | Disable a certain workaround on a device. |
Hardware profiles allow you to disable driver workarounds, and test and validate driver fixes. You also don’t need to modify and re-build the Unity SDK:
public class DefineProfilesScript : AndroidHardwareProfiles
{
public override void DefineHardwareProfile(ProfileDatabase database)
{
DefaultDeviceFilter myDefault = database.GetDefaultFilter();
// Disable every driver workaround on default profile
myDefault.DisableAllWorkarounds();
// o1s is the codename of the S21 device.
var s21 = database.CreateFilter("","","Samsung","o1s");
// Disable a driver workaround on a specific device.
s21.SetWorkaround("HasBuggyBackBufferCopyImage", State.Disabled);
}
}
You can also enforce driver workarounds, without waiting for Unity to distribute a new SDK version with hard-coded patches:
public class DefineProfilesScript : AndroidHardwareProfiles
{
public override void DefineHardwareProfile(ProfileDatabase database)
{
DefaultDeviceFilter myDefault = database.GetDefaultFilter();
// Filter for Google Pixel 6 devices
var pixel6 = database.CreateFilter( "", "", "((G|g)oogle)", "(oriole|raven|bluejay)");
// Manually apply an existing driver workaround.
pixel6.SetWorkaround("HasBuggyBackBufferCopyImage", State.Enabled);
}
}