Fabric crash debugging

Crashes are evidence. Read them in a fixed order and you will find the cause in the first 50 lines almost every time. Never "fix" a crash by guessing; locate the frame first.

Where to look

If the user pastes only the last lines, ask for the whole crash report or latest.log - the cause is near the top, the bottom is just main unwinding.

Reading a crash report, in order

1. Description line (Description: ...) - what the game was doing (ticking entity, rendering screen, initializing game, loading level).
2. The exception type and message - the first java.lang.... / org.spongepowered... line.
3. Caused by: chain - scroll to the last Caused by:; it is usually the real cause.
4. The first stack frame in mod code - look for your package (com.example.examplemod) or a mixin handler (handler$xyz000$examplemod$methodName, or the merged method name with your examplemod$ prefix). That frame is your starting point.
5. "Mixins in Stacktrace" / mixin info section (Fabric adds it) - lists which mods' mixins are applied to the classes in the stack. A different mod may be the cause.
6. System details at the bottom: Minecraft version, Java version, Loader version, mod list. Check for duplicates and for mods built for another Minecraft version.

Loader resolution errors (game never starts)

latest.log shows Incompatible mods found! or Mod resolution encountered an incompatible mod set! with lines like:

- Mod 'Example Mod' (examplemod) 0.1.0 requires version 0.165.0 or later of fabric-api, which is missing!
- Mod 'Example Mod' (examplemod) 0.1.0 requires any version of minecraft between 26.2 and 26.3 (exclusive), but only the wrong version is present: 26.3!

Fixes: install/update the named dependency, or correct the range in fabric.mod.json depends. Also check for: two copies of the same mod, a mod with a duplicate id, a breaks entry triggering, wrong "java" range.

Mixin failures

Tools:

• Add -Dmixin.debug.export=true to the run config, reproduce, and read run/.mixin.out/class/... (decompile in the IDE) to see what was actually generated and which mods touched that class.
• -Dmixin.debug.verbose=true logs each mixin as it applies.
• -Dmixin.dumpTargetOnFailure=true dumps the target class when an injection fails.

Client / server side crashes

Typical messages on a dedicated server:

java.lang.RuntimeException: Cannot load class net.minecraft.client.Minecraft in environment type SERVER
java.lang.NoClassDefFoundError: net/minecraft/client/gui/screens/Screen
java.lang.ClassNotFoundException: net.minecraft.client.player.LocalPlayer

Cause: common code (src/main, the main entrypoint, a common mixin, a payload record, a static initializer, or a lambda) references a client-only class. The JVM loads the class the first time a method that mentions it is verified, so even an unexecuted branch can crash.

Fixes:

• Enable splitEnvironmentSourceSets() (see fabric-project-setup) so the compiler rejects this; move client code to src/client.
• Move client mixins to the client mixin config.
• Never put client types in method signatures, fields or lambdas of common classes. Route through the client entrypoint, an interface, or a packet.
• Logical-side bugs (singleplayer works, server does not) usually mean logic ran on level.isClientSide(), or the client mutated state the server never learned about.

Version-mismatch errors

java.lang.NoSuchMethodError: 'void net.minecraft.client.gui.GuiGraphics.drawString(...)'
java.lang.NoSuchFieldError: ...
java.lang.AbstractMethodError: Receiver class ... does not define or inherit an implementation of ...
java.lang.IncompatibleClassChangeError

A mod (yours or another) was compiled against a different Minecraft or library version than the one running. Check: the mod jar targets this exact MC version; fabric.mod.json range is not too wide ("minecraft": "*"); the dependency jar matches; you are not running the -dev jar (pre-26.1) outside the dev environment.

Common runtime exceptions in mod code

• NullPointerException on Minecraft.getInstance().player / .level - accessed on the title screen or during world join. Guard with null checks.
• ConcurrentModificationException / "Accessing LegacyRandomSource from multiple threads" / "Async ... not on the main thread" - world access from a network or worker thread; schedule it with server.execute(...) / client.execute(...).
• IllegalStateException: Registry is already frozen / registering too late - register in onInitialize, not on world load or lazily.
• Missing model/purple-black textures: not a crash; the log says which resource path was expected (assets/<modid>/...). Check namespace and file names (lowercase).

Build (Gradle / Loom) failures

Run with --stacktrace (or --info) to get the real cause of a Gradle failure.

Workflow when the cause is not obvious

1. Reproduce in dev with only your mod + Fabric API.
2. If it only happens with other mods, add them back in halves (binary search) until the pair is found; then read the mixin section of the crash report for both.
3. Add a breakpoint at the first mod frame and run runClient in debug mode, or add a LOGGER.debug with the values involved.
4. Write down the root cause before changing code, and make the smallest fix.

Common mistakes

• Reading only the bottom of the stack trace.
• Lowering require/defaultRequire or wrapping code in try/catch(Throwable) to make a crash "go away" - the feature silently stops working.
• Blaming Fabric API or Minecraft before checking which mod's frame or mixin is involved.
• Treating hs_err_pid (native) crashes as Java bugs in the mod.
• Fixing a dedicated-server ClassNotFoundException by wrapping the call in an isClient check instead of moving the code out of the common class.
• Asking the user for "the error" and then working from a screenshot of the last 10 lines - ask for the full latest.log or crash report file.