TROUBLESHOOTING & FIXES

Complementary Shaders Not Working: Troubleshooting Guide

Illustration for: Complementary Shaders Not Working: Troubleshooting Guide

When Complementary Shaders does not work, the failure is almost never mysterious, it belongs to a short list of causes that repeat across thousands of players: a file in the wrong place, a loader that does not match the game, a second mod fighting for the renderer, or settings the hardware cannot carry. This guide is the triage hub: identify your symptom, run the universal checks, and follow the link to the fix written for your exact problem.

The five universal checks (run these first)

  1. Right edition: Minecraft Java Edition. There is no Bedrock version of the pack, if you are on Bedrock, start with the Bedrock guide instead of troubleshooting.
  2. Loader present and matched: Iris or OptiFine installed, in the build made for your exact Minecraft version, and actually running (title screen shows it). A vanilla profile has no shader menu at all.
  3. File correct and placed correctly: the genuine ZIP (right name, ~0.5 MB), unextracted, directly in the shaderpacks folder, ZIP checks and folder locations.
  4. Pack actually selected: chosen in the shader menu, not merely present in the folder (enabling).
  5. One variable changed: if it broke after something changed, a game update, a new mod, a driver update, that change is your prime suspect. Undo it mentally before touching anything else.

Symptom router

SymptomYour guide
The pack is not in the shader list at allNot showing in the shader list
World is black or blank with the pack onBlack screen fixes
Game crashes when enabling the pack or loading a worldCrash fixes
It loads, but lighting/shadows/water look wrongBroken lighting, shadows and reflections
It worked until Minecraft updatedAfter a Minecraft update
It works, but frame rate is poorIncrease FPS
Frame rate is fine but the game stuttersLag and stuttering

The isolation method

If the universal checks pass and the symptom is strange, isolate variables like a technician:

  1. Vanilla test: disable shaders. Does the problem persist? If yes, it is not the pack, it is the game, a mod, or the machine.
  2. Stock profile test: re-enable the pack on its default profile, no overrides. Many "bugs" are a forgotten experimental setting.
  3. Clean folder test: remove other packs and temporarily move out other mods, especially rendering-related ones. Add back half at a time.
  4. Fresh file test: download the current release again and replace your ZIP. Files do get corrupted, and old versions do get mistaken for current ones, check the version against the release history.
  5. New world test: if one world misbehaves and others do not, the problem lives in that world or its mods, not the pack.

Before you ask for help anywhere

Whether you ask on a forum, a Discord, or of a friend, the answers come faster when you bring: your Minecraft version, your loader and its version, the pack version (from the filename), your GPU, and what changed last. "Shaders not working" with those five facts is a solvable problem; without them it is a guessing game. The pack's official community channels are listed on its official site and listings.

How triage differs between Iris and OptiFine

The universal checks are the same for both loaders, but the next question you ask depends on which one you run. With Iris, start by confirming the surrounding stack: Iris is normally used alongside Sodium, and both pieces must belong to the same Minecraft version. A pack that fails only in the Iris profile, while the same version of the game runs cleanly in vanilla, points first to a version mismatch somewhere in that stack rather than to the pack file itself. Check the loader build and the companion mods as a set before you touch the pack.

With OptiFine, start by returning its own video and performance options to defaults while you diagnose. OptiFine carries more rendering switches of its own, and a switch left in a non-default state can change how a pack is applied or produce a picture that looks like a pack fault. Note which loader and exact build you are running before you change anything. If you try the other loader as a test, treat it as a new baseline and re-run the five universal checks: a symptom that follows the pack across both loaders is about the file, its settings file, or the hardware; a symptom that stays with one loader is about that loader's version or options.

Reading the game log without guessing

You do not need to understand the whole game log to get value from it. Open it after a failed attempt, ideally after a single, clean reproduction where you changed nothing else, and search rather than reading top to bottom. Look first for the pack's filename: if the loader never mentions the ZIP at all, the problem is placement or recognition, which routes you to the not-showing guide rather than to rendering fixes. Look next for wording around shader compilation: shader code is compiled by the graphics driver when the pack is applied, so compile failures in the log point toward the driver, the GPU actually in use, or a version mismatch, not toward your world or your settings. Mentions of another mod's name close to the failure point are also worth noting, especially if that mod touches rendering, the sky, or lighting.

What the log cannot do is give you a single magic line that names the fix. Treat what you find as a routing clue: filename absent, route to placement; compile failure, route to GPU and driver checks and version matching; failure only when a world loads, route to world and mod isolation. Copy the few lines around the failure if you later ask for help, a short, relevant excerpt is far more useful to a helper than the entire log, and it avoids burying the clue. If the log shows nothing unusual at all, that is information too: the loader believed the pack loaded, so look next at selection, settings, and whether the picture you are seeing is the style working as designed.

Recovery order when several fixes have already failed

When you have already tried a handful of fixes and the setup is now in an unknown state, stop adding changes and rebuild a known baseline in a fixed order. First, return to a vanilla profile with no shaders and confirm the game itself is stable in a test world. Second, re-enable only the loader, in the build for your exact Minecraft version, and confirm the shader menu appears. Third, place a freshly downloaded copy of the current release, r5.9.3, around 0.53 MB, still zipped, directly in the shaderpacks folder, with any old settings .txt file for that pack moved aside so the pack starts from defaults. Fourth, select the pack, load the same test world, and only then judge the result. Change nothing else between those steps.

This order matters because each step can fail independently, and the step where it fails tells you which guide to follow next instead of restarting the whole search. If the baseline works, reintroduce your own things one session at a time: your settings first, then other packs, then other mods in halves. If the baseline itself fails at the compile or selection stage, you have narrowed the field to loader version, driver, or GPU before any of your customisations are involved. Keep a short written note as you go, what you changed, in what order, and what happened. That note is both your fastest route back to the last working state and, if you still need help, the clearest summary you can hand to a support channel alongside your Minecraft version, loader version, pack filename, and the GPU shown on the F3 screen.

Frequently asked questions

It worked yesterday and nothing changed. Really?

Something almost always changed, a silent launcher update, a driver update, a mod that updated itself. The universal checks catch most of these; the isolation method catches the rest.

Should I reinstall everything?

As a last resort, not a first step. Reinstalling destroys the evidence of what was wrong and usually re-creates the same mismatch. Work the checks first; they are faster.

Is the pack itself buggy?

Like all software it has had bugs across its history, which is why small revisions follow feature updates. Running the current release (r5.9.3) eliminates the known-and-fixed category before you troubleshoot your own setup.