Troubleshooting

Minecraft will not launch

Check the loader error first. For 0.5.1, verify Minecraft 26.3, Java 25+, Loader 0.19.4+, Fabric API 0.160.5+, and Sodium 0.9.2+, all built for the correct game version.

Test with only Fabric API, Sodium, and Sulkan. If the clean instance works, add other mods individually to find the conflict.

The game runs without shaders

Check the title-screen renderer message. An OpenGL fallback pauses Sulkan effects. Update GPU drivers, verify GPU selection, choose Use Vulkan next launch when offered, and restart.

Also check that shaders are enabled and a supported pack is selected in Video Settings → Shaders.

A pack does not appear

• Published 0.5.1 scans the active instance’s shaders/ folder.
• Use a folder or ZIP, directly inside that directory.
• Include exactly one sulkan.json at the root or in one wrapper directory.
• Check case-sensitive shader paths and valid JSON.
• A pack without a native manifest is unsupported, even if it works in Iris.

Try the starter pack to separate a pack problem from an installation problem.

Compilation or validation fails

Read logs/latest.log in your active instance. Search for Sulkan, the pass name, or the shader filename around the first error.

Message or symptom	What to check
Unknown manifest field	Use the format 1 field reference
Missing pack file	Match path and filename case; paths resolve from the manifest root
Multiple writers or a cycle	Give each intermediate its own resource and use explicit reads
Unsupported native pack version	sulkan.json must declare "version": 1
GLSL failure	Begin with #version 450; check bindings and includes
Budget or device limit	Lower image scale/quality or simplify allocations

A failed candidate settings compile keeps the previous generation. A dynamic scene-shader failure can pause the pack after completing the frame with compatible vanilla pipelines.

Low frame rate or memory pressure

Start at Medium and lower shadow distance, cloud quality, and reflection quality. Compare the same view with shaders disabled. Check that Minecraft is using the intended GPU.

A pack’s declared budget describes the active generation. During a reload, retired and replacement generations can coexist until GPU work completes, so it is not a device-wide VRAM cap.

Ask for help

Use the support page for community help, bug reports, and what to include in a report.