Minecraft mod not loading? Universal Modder troubleshooting for Java, loaders & recipes

Locate the first stage that fails

“The mod does not work” can describe a failed compile, a crash before the menu, a missing item, or a broken texture. First record which stage fails. Work in a separate test instance and keep a copy of the original world before experimenting.

Game without the new mod: does your existing instance reach the menu?
Matching loader alone: can it start with the intended game version?
One new mod and required dependencies: which error appears first?
A new test world: can you obtain and use the feature?

Use the development workspace's run/logs/latest.log for a dev client. For an installed mod, use logs/latest.log inside the launcher's selected instance, plus a crash report under crash-reports/ when one exists. A launcher console may explain Java or download failures before a game log is created.

Java or Gradle fails before the game starts

What you see	What to inspect	Next reversible check
`UnsupportedClassVersionError`	The class was built for a newer Java runtime than the one loading it	Compare the launcher's runtime and `gradlew --version` with the versioned loader docs
`invalid source release: 21`	The selected compiler does not support that target	Point the development toolchain at JDK 21 for the 1.21.1 exercise
Cannot resolve an artifact or download a Gradle distribution	The first network/HTTP error, wrapper URL and dependency coordinates	Confirm the official wrapper and network access; preserve the full error before retrying
Build appears idle during the first setup	Gradle download/decompile progress	Allow the initial dependency setup to finish; avoid starting a second build against the same workspace

.\gradlew.bat --version
.\gradlew.bat build --stacktrace

./gradlew --version
./gradlew build --stacktrace

Do not change the source level solely to silence the error. Keep the game, loader, API and Java combination consistent with the project you are building.

The loader refuses the mod or reports a dependency

Copy the exact mod ID and required version range from the first loader error. Then compare it to the metadata inside the JAR and the actual installed dependencies.

Wrong loader: a Fabric mod belongs in a Fabric instance, and a NeoForge mod in the matching NeoForge instance. Changing the file extension cannot convert it.
Wrong game version: 1.20.1 and 1.21.1 have different APIs and resource conventions. Follow the declared range, not the filename alone.
Missing library: install the loader- and game-matched dependency listed by the mod, such as Fabric API when that mod requires it.
Duplicate mod ID: close the game and keep one main JAR for that mod in the test instance.
Wrong folder: use the instance selected by your launcher; its mods/ folder may be outside the default .minecraft.

The loader and Java guide lists source-backed combinations and explains why launcher Java and build Java may differ.

The game loads, but the item, recipe or texture is missing

Symptom	For the 1.21.1 practice example
`Unknown item` for `/give`	Confirm the mod loaded. Match `fieldguide` in Gradle metadata and `@Mod`, and register the `DeferredRegister` on the mod event bus
Item exists, but cannot be crafted	Check `data/fieldguide/recipe/copper_token.json`, singular `recipe`, the result `id`, and recipe errors after world load or `/reload`
Purple/black item texture	Model: `assets/fieldguide/models/item/copper_token.json`. Texture: `assets/fieldguide/textures/item/copper_token.png`. Match the model reference and file case
Translation key appears as the item name	Check `assets/fieldguide/lang/en_us.json` and `item.fieldguide.copper_token`; test with the corresponding language or add its locale file
Item works with `/give`, absent from the creative tab	Check the creative-tab event listener and the targeted Ingredients tab. Item registration and creative placement are separate steps

These file paths target the tutorial's NeoForge 1.21.1 example. Use documentation for your exact release when adapting to another version.

The dev client works; the installed JAR fails

Test the built artifact, not only the IDE run. Use the main JAR from build/libs/; a -sources.jar or -javadoc.jar is not the playable mod. Open the JAR with an archive viewer and check for the compiled entry class, loader metadata, and assets/fieldguide/ / data/fieldguide/ resources.

A model can render correctly in an editor and still be the wrong installation file. The MC Mod Maker download guide distinguishes an editable .bbmodel, a texture, a source ZIP and a built Fabric JAR; its Fabric export does not run in a NeoForge instance. Check the exported file type and loader before investigating gameplay. This is a reference to our separate creation tool, not a game-test result.

Use a separate launcher profile with the same game and loader versions. Confirm the actual file was copied, restart the profile, and repeat the feature and saved-world checks. If a test only passes in the development client, mark the distributed artifact as unverified.

Give your agent an error it can investigate

A useful report includes your OS, edition, game/loader versions, launcher instance, Java versions, JAR filename, last change, first relevant exception, and smallest reproduction. Remove secrets, usernames and private paths before sharing logs publicly.

Diagnose this Minecraft mod failure. Use my exact game, loader and Java versions. Read the first relevant error in latest.log or the build output, identify the failing stage, and compare it to the matching official docs. Propose one reversible test. Do not overwrite my world or update several dependencies at once. Report which checks actually ran.

Keep the full cause chain around the first exception, not just a generic launcher exit code. After one fix, reproduce the same test before adding the rest of your mods.

A SMALL BASELINE TO START FROM Follow the Copper Token walkthrough

Sources & version notes

Instructions were checked against the versioned documentation and repository snapshots below on October 7, 2026. Match them to the edition and loader you actually use.