23. Troubleshooting and known issues¶
A layer renders live but does not cache. The inspector says why: a choke without a mask under it, an anchor whose target is not evaluated, or a node the baker cannot understand. Fix the cause, or leave it live; live is always correct.
A procedural re-bake looks wrong after undo. Update to the current build; the undo-heal is byte-exact now. If it recurs, note whether the object is parked and report it.
The GPU baker is not found. Overpaint falls back to Cycles for bakes and UV transfers. On Windows make sure the extension was installed from the complete zip. Set the environment variable OVERPAINT_TORCH_TRANSFER=0 to force the Cycles transfer deliberately.
A project opens without its cache folder. Move the .op_image_cache folder alongside the .blend, or press Cache All to rebuild it. Overpaint releases missing cached proxies and uses the live graph while the folder is absent.
A dropped image lands on Color. The sidebar importer attempts filename inference, but in this build some label-to-channel-key hints do not resolve (especially roughness, normal, metallic, AO, emission and opacity). Check the channel ribbon after every drop and retarget the new Image sublayer when needed.
Material Paint strokes do not commit. On macOS and Linux the stroke release is not detected in 1.0 (it uses the Windows mouse API). Disable Material Paint to commit what you painted, or paint channel by channel.
A Grunge generator bakes differently from its live preview. The six Grunge variants' GPU bakes do not yet match their previews; keep those sublayers live (chapter 7.2) until the baker update.
Blender crashes in texture paint on Vulkan. See the known issues below; the Vulkan issues are mitigated in the addon where possible and reported upstream.
Known issues that live in Blender or the GPU driver rather than in Overpaint:
| ID | What | Backend | Status |
|---|---|---|---|
| VK-001 | crash in texture paint from an image barrier null-deref | Vulkan | mitigated in the addon |
| VK-002 | descriptor-set crash during shader preview | Vulkan | open, guarded |
| VK-003 | preview-thread crash on sublayer removal | Vulkan | open |
| GL-001 | materials with more than 32 texture samplers fail to compile | OpenGL | use Vulkan: the Switch to Vulkan button at the top of the OP Painter tab (chapter 2), then restart Blender |
Blender 4.5 is the tested version. Blender 5.x is ported and works correctly too