Troubleshooting Guide

Most Minecraft client problems fall into a handful of categories: crashes on launch, injection failures, missing dependencies, and version conflicts. This guide covers each category with specific diagnostics.

Crash on launch

Symptoms: Minecraft closes immediately after clicking Play, or shows a crash dialog with a stack trace.

Common causes and fixes:

• Loader mismatch. The client was built for a different Minecraft version. Check the client page for supported versions and confirm your Fabric or Forge profile matches.
• Missing dependency. Some clients require additional Fabric mods such as Fabric API. Check the client page for dependencies and install them in the same mods folder.
• Conflicting mods. Two mods modifying the same class can cause a crash. Remove all mods except the client and re-test. Add mods back one at a time to identify the conflict.
• Insufficient memory. Modded Minecraft needs more RAM than vanilla. In the launcher, edit the profile and set the JVM argument -Xmx4G for 4 GB of RAM.

Client does not appear in-game

Symptoms: Minecraft launches, but the client menu does not open and the client's watermark is not visible.

Common causes and fixes:

• Wrong mods folder. Confirm the .jar file is in the correct mods folder for the profile you launched. If you have multiple Minecraft installations, each has its own mods folder.
• Nested folder. If you extracted a .zip and moved the containing folder into mods, the .jar is not at the top level. Move the .jar itself into mods.
• Wrong profile. Confirm the launcher profile is set to Fabric or Forge, not to the vanilla profile.
• Client not loaded by the loader. Open the mod list in-game (from the main menu) and check if the client .jar is listed. If it is not, the loader did not load it.

Injection failures (runtime clients)

Symptoms: The client uses runtime injection and the injection step fails, produces an error, or the client does not attach to the running game.

Common causes and fixes:

• Antivirus blocking. Some antivirus tools block runtime injection by default. Add an exception for the client directory or disable the antivirus temporarily while testing.
• Java version. Runtime injection depends on the exact Java version. Confirm your system Java matches the version Minecraft uses. Most modern Minecraft releases require Java 21.
• Launcher incompatibility. Some third-party launchers interfere with injection. Test with the official Minecraft launcher.

Missing dependencies

Symptoms: Crash log mentions "NoClassDefFoundError" or "class not found", or the client's menu opens but some modules are missing.

Common causes and fixes:

• Fabric API. Many Fabric clients require Fabric API. Download it from Modrinth or CurseForge and place it in mods.
• Specific libraries. Some clients bundle their own dependencies, others expect them separately. Check the client's README or GitHub release notes for the dependency list.
• Version mismatch. A Fabric API build for 1.21.1 will not work with a client compiled for 1.21.5. Match the dependency version to your Minecraft version.

Version conflicts

Symptoms: The client loads but behaves incorrectly, crashes when opening specific menus, or produces rendering glitches.

Common causes and fixes:

• Loader version. Fabric Loader itself has versions. An outdated loader may not support the client's mixin version. Update Fabric Loader through the installer.
• Conflicting mixins. Two mods modifying the same Minecraft class can create subtle bugs. Remove non-essential mods and re-test.
• Client version for wrong MC build. Confirm the .jar filename includes the correct Minecraft version. A "1.21" build will not work on "1.21.5".

Reading the crash log

The crash log lives at .minecraft/crash-reports/. The most recent file is named with a timestamp. Open it in a text editor and search for:

• Description: — a one-line summary of the crash.
• Caused by: — the first cause is usually the root issue.
• at com.example.client — stack frames referencing a client class usually point to the responsible mod.
• java.lang.NoClassDefFoundError — indicates a missing dependency.
• java.lang.NoSuchMethodError or NoSuchFieldError — indicates a version mismatch between mods.

Getting more help

If the troubleshooting steps above do not resolve your problem, check the client's GitHub issues page and its Discord server. When asking for help, include the full crash log, your Minecraft version, your loader version, and the client version.