Fix ClassNotFound and NoSuchMethod errors in a Minecraft mod
These errors mean the game found code at run time that does not match what your mod was built against. NoClassDefFoundError: a class is missing, often an optional mod that is not installed, or a library that was not packed in the jar. NoSuchMethodError and NoSuchFieldError: the class exists but its method changed, usually because the mod was built for another version of Minecraft or of the other mod. Read the first line: it names the class or method. Then check the version in your dependencies, and keep code that touches an optional mod in its own class, called only when the mod is there.
Works on Minecraft 1.20.1 to 26.3 on NeoForge; Minecraft 1.16.5 to 26.3 on Fabric; Minecraft 1.16.5 to 1.20.1 on Forge; Minecraft 1.12.2 on Forge. Each example was compiled against its loader and version before it shipped in Linen.
- Read the first line of the error. It names the missing class, method or field.
- Find which jar should supply it, and check that jar is installed in the version you built against.
- If the owner is an optional mod, test for it first and call its classes only from a separate class.
- If it is your own class, check the build packs it, and that the name and package match.
- If the method changed between versions, rebuild against the version the player runs.
What you can change
Section titled “What you can change”The example uses these values. Change them in the code.
| Setting | In the example | What it does |
|---|---|---|
| api | com.example.othermod.OtherApi |
The full name of one class from the other mod. |
For each loader and version
Section titled “For each loader and version”The example mod is examplemod in the package com.example.examplemod. Use your own mod id and package.
Fabric and NeoForge 1.20.4 to 1.21.1, NeoForge 1.20.1 to 1.20.2, Fabric 1.16.5 to 1.20.3, Fabric and NeoForge 1.21.2 to 26.3, Forge 1.16.5 to 1.20.1, Forge 1.12.2
Section titled “Fabric and NeoForge 1.20.4 to 1.21.1, NeoForge 1.20.1 to 1.20.2, Fabric 1.16.5 to 1.20.3, Fabric and NeoForge 1.21.2 to 26.3, Forge 1.16.5 to 1.20.1, Forge 1.12.2”Uses:
Class.forNameClassNotFoundExceptionLinkageError
src/main/java/com/example/examplemod/compat/OptionalModCheck.java
package com.example.examplemod.compat;
// Optional Mod: checks whether another mod's class exists before your code touches it. Calling a class that is not there throws// NoClassDefFoundError and crashes the game; Class.forName with 'false' only looks, so you can test first.public final class OptionalModCheck { /** True when the other mod is installed. Keep any code that uses its classes in a separate class, and call that class only when this is true. */ public static final boolean PRESENT = has("com.example.othermod.OtherApi");
private OptionalModCheck() { }
public static boolean has(String className) { try { Class.forName(className, false, OptionalModCheck.class.getClassLoader()); return true; } catch (ClassNotFoundException | LinkageError e) { return false; } }}Sources
Section titled “Sources”- https://docs.fabricmc.net/1.21.1/develop/events
- https://docs.neoforged.net/docs/1.21.1/gettingstarted/modfiles
Related how-tos
Section titled “Related how-tos”- Find out why a mod is not in the mod list
- Publish my mod on Modrinth or CurseForge
- Armor that gives a potion effect
- Do something when a player joins
- Fix a wrong Java version error
In Linen
Section titled “In Linen”Linen’s How-tos library has this page too, with the example for your own mod’s loader and Minecraft version. Hover a name in your code and Linen points to the how-tos that explain it. Both are free. Download Linen.