Guidefor players3 min read
Fixing "Incompatible mod set" and other startup crashes
The loader tells you exactly what is wrong before the game starts. How to read that screen, and the halving method for when it does not name a cause.
The error screen is the answer
An "incompatible mod set" screen looks intimidating and is the most helpful error Minecraft modding produces. The loader checked every mod against every other mod before starting the game, and it is telling you precisely what does not fit.
A typical entry:
Mod 'Sodium Extra' (sodium-extra) 0.6.0 requires version 0.6.x of sodium,
which is missing!
You should install version 0.6.x of sodium for the optimal experience.
Three facts in one sentence: which mod is unhappy, what it needs, and what is missing. That is a shopping list, not a mystery.
Read it in order
The list is not ten independent problems. Fix the first one and re-run, because most of the rest are consequences of it.
Four shapes cover nearly everything:
"requires version X of Y, which is missing" — a dependency is not installed. Install it, at that version.
"requires version X of Y, but only version Z is present" — installed, wrong version. Either update the dependency or use an older build of the mod that wants it.
"is incompatible with" — two mods that cannot coexist. They usually do the same job. Pick one.
"requires Minecraft version X" — the mod is for a different Minecraft version. There is no configuration that fixes this; get the build for your version.
The three checks that prevent most of this
Before debugging, confirm the basics, because they cause the majority of these screens:
- Fabric API is installed. If the game starts with no mods loaded at all, this is almost always why. It is a separate download and most Fabric mods need it.
- Every jar is for your exact Minecraft version. Not the line. 1.21.1 and 1.21.4 are different.
- Every jar is for your loader. One NeoForge jar in a Fabric folder produces an error that never uses the word "loader".
Checking mod compatibility covers how to verify all three before installing rather than after.
When it crashes instead of listing problems
A real crash produces a report in crash-reports/. It is long. Almost none of it matters.
Find the line beginning Caused by: and read the few lines under it. That is the actual
failure. Everything above is the call stack that led there and everything below is the
machine's specification.
Caused by: java.lang.NoSuchMethodError:
'net.minecraft.class_1234.method_5678()'
at com.example.somemod.SomeClass.init(SomeClass.java:42)
com.example.somemod names the mod. NoSuchMethodError means it called game code that does
not exist in your version, which means it was built for a different one.
Two more you will meet:
NoClassDefFoundError— a dependency is missing. Same fix as above.OutOfMemoryError— not a mod problem. Allocate more memory to the game.
Halving, when nothing is named
Sometimes the report blames the game rather than a mod. Do not read further, and do not guess. Halve it:
- Move every mod out of
mods/. Confirm the game starts. If it does not, the problem is the loader or the installation, not a mod. - Put half back. Start.
- If it crashes, the culprit is in that half. If it starts, it is in the other half.
- Halve again. Repeat.
Forty mods takes about six rounds. Removing them one at a time takes forty, which is why people give up and reinstall instead. Keep the mods you removed in a separate folder so you can put them back exactly.
Getting help usefully
If you end up asking someone, the useful message contains:
- The Minecraft version and the loader version
- The full log, uploaded somewhere, not a screenshot of part of it
- The mod list
- What you changed immediately before it broke
The last one is the most valuable and the most often omitted. "It worked yesterday and today I added two mods" narrows the search to two things.