Guidefor modders3 min read
Why a Fabric mod will never run on NeoForge
Not a licensing choice or a rivalry. A mod is compiled against one loader's API and patched into the game by that loader's machinery. What that means in practice.
Minecraft has no mod support
Start here, because everything else follows from it. Mojang does not ship a modding API for Java Edition. There is no documented extension point, no plugin interface, nothing the game offers to code that wants to change it.
So a mod loader is not a plugin system. It is a program that rewrites the game's compiled code at startup to insert hooks that were never there.
Once you know that, "why can't I use a Fabric mod on NeoForge" answers itself: the two loaders rewrite the game differently, insert different hooks in different places, and offer mods a different set of things to call.
What a mod is actually compiled against
When you build a Fabric mod, you compile against Fabric's API. Your code contains direct references to Fabric's classes and methods, baked into the jar as symbols.
Load that jar on NeoForge and the very first thing it does is look for a class that is not there. It fails immediately, before any of your logic runs. This is not a check the loader performs and could choose to skip. It is Java being unable to find a class.
The same applies in reverse, and it is nothing to do with the game or the licence. It is what compiling against a library means.
Three things that differ, not one
If it were only the class names, a rename tool could work. It is not.
The entry point. Fabric declares mods in fabric.mod.json and calls an initialiser
interface. NeoForge uses neoforge.mods.toml and an annotated class with a constructor the
loader calls. Different files, different shapes, different contents.
The lifecycle. Both loaders start mods, load registries and fire events, but at different moments and in a different order. Code that registers a block at the right time on one loader registers it too early or too late on the other, which fails in ways that are much harder to debug than a missing class.
The registry system. Adding a block means telling the game a block exists. Each loader provides its own mechanism for that, wrapping vanilla's internals in its own way. There is no shared vocabulary underneath.
A converter would have to translate all three, correctly, for every mod and every game version. That is not a converter, it is a reimplementation of one loader on top of the other, which people have attempted and which is fragile enough that nobody depends on it.
Why mods are pinned to a Minecraft version too
The same reason, one level down. The loader patches the game's compiled code, so it needs to know exactly what that code looks like. Mojang ships obfuscated builds and changes internals freely between versions, because they are internals and nothing is supposed to depend on them.
So when 26.2 renames a method the mod called, the mod stops working. Not because it was forbidden, but because the thing it was calling is no longer there under that name.
This is why every mod on this site lists exact versions rather than ranges, and why the mod catalogue filters on the exact version rather than the release line.
How authors ship for both
The good ones structure the project in three parts:
- a common module with the actual game logic, written against neither loader
- a fabric module: a thin adapter that registers the common code Fabric's way
- a neoforge module: the same adapter, NeoForge's way
Tooling such as Architectury exists to make this less painful, and multi-loader templates are common. It is still two builds, two test runs and two releases per Minecraft version, which is why plenty of authors reasonably pick one.
If you are choosing which to support first: Fabric reaches a new Minecraft version sooner and is less work; NeoForge is where the large content mods and their users already are. Which loader should you use goes into the trade.
The practical version
- One loader per installation. Never mix jars from different loaders in one folder.
- A mod's page lists its loaders. If yours is not on that list, the mod does not run on it, and no setting changes that.
- If you want the same content on a different loader, look for a separate build by the same author, or an equivalent mod. There is no file conversion step.
- If you want something that runs everywhere with no loader at all, that is a data pack.