Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Workarounds

Learn about workarounds and how to enable or disable them for specified devices.
Read time 4 minutesLast updated 13 days ago
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.

How Unity handles workarounds

Unity’s Vulkan back-end includes built‑in device and driver workarounds that Unity applies automatically based on:
  • Vendor ID
  • Device ID
  • Driver version
  • Operating System (OS) version
  • API
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.

Workarounds in scripts

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 Build, then check the logcat output.
For a list of possible workarounds you can toggle, refer to Workaround options.

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 shader 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.
HasBuggySubpassMerging
The driver corrupts attachment data when it merges a subpass that reads a loaded color attachment as an input attachment.

Workaround states

Use the following states to set the status of the workaround options:

State

Description

DefaultLet the system decide whether to apply the workaround.
EnabledEnable a certain workaround on a device.
DisabledDisable a certain workaround on a device.

Disable workarounds on all or certain devices

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);     }}

Enforce driver workaround

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);    }}

Additional resources