Fixing Iris Shaders Load Failures, Sodium Conflicts, and GPU Errors

When Iris Shaders refuses to load or behaves unexpectedly, the mod's own messages point to a small set of causes: a missing or mismatched Sodium, a GPU that cannot handle what a pack requests, or a crash handler interfering with the game. This guide covers what each on-screen error means and which actions resolve it.

Sodium Requirements

Iris depends on Sodium for acceptable performance, and it checks for it at startup. If Sodium is absent, Iris reports that it requires Sodium and asks you to obtain Sodium, put it in your mods folder, and relaunch. If a version is present but incompatible, Iris says so and asks for the correct version, with the wrong one removed, followed by a relaunch. In both cases the fix is the same shape: make sure a compatible Sodium build is present alongside Iris, then start the game again.

Shader Pack Load Failures

A pack that will not start produces one of several messages. The general failure notice states that Iris hit a problem loading the shader and asks you to report it to the Iris developers. A pack-specific failure asks you to send the error to whoever made the pack. If the pack uses features your hardware does not support, Iris reports it as incompatible and suggests trying a different pack. One specific case names the unsupported feature directly: the pack asked for SSBO, which your GPU does not provide, so the pack may not work correctly.

Reload and toggle operations can also fail on their own, with Iris reporting the reason for the failed reload or the failed toggle. Read the reason given, since it identifies what went wrong.

On macOS, keep in mind that Iris notes the platform is known to have trouble with many shader packs. If a pack misbehaves there, testing another pack is the practical step.

Managing Packs in the Selection Screen

The Shaderpack Selection Screen is where packs are chosen and maintained. Available actions there include:

• Open Shader Pack Folder... to reach the folder holding your packs.
• Shader Pack Settings... to adjust the selected pack.
• Shader Pack List... to view packs.
• Refresh Shader Packs to rescan what is available.
• Import settings from a file, and export the applied settings to a file.
• Reset all options and apply, or set a single option back to its default value.

To add packs, drag and drop shader pack files onto the interface. A successful drop reports the pack as added. If the files are not valid packs, Iris says so; a single invalid file is named as not a valid pack. A pack that cannot be copied is reported, and a pack already in your folder is flagged as a duplicate. Importing more than one settings file at once is rejected, and a settings import that fails is reported by filename.

If nothing is available, the screen shows that no packs are present. Some operations require leaving fullscreen first, which Iris will tell you.

Shadow Distance

Max Shadow Distance controls how far terrain and entities can cast shadows; anything past that distance casts none. Reducing it can raise frame rates noticeably. If the current pack defines its own shadow render distance, the option is locked and cannot be changed. The effective distance is also limited by your view distance setting.

Debug Logging

Enabling debugging makes log output more verbose, which helps when diagnosing a failure. Turning it off returns logging to normal. Two situations prevent full debugging: if your computer does not support debug features, Iris cannot enable client debugging, though shader debugging still turns on; and if no debug context exists, you must restart the game to enable OpenGL client debugging. On NeoForge, OpenGL debugging is unsupported, so shader debugging is enabled instead.

Crash Handlers

If Not Enough Crashes is detected, Iris warns that it can badly break the game while handling crashes and does not give accurate results. MixinTrace is suggested instead, since it identifies crash causes more reliably and leaves the game in a valid state.