How to update your mod to a new Minecraft version
Update in this order. First read the loader’s migration notes for the new version (Fabric, Forge and NeoForge all publish them). Then change the Minecraft, loader and API versions in your build files, and the Java version if it changed (1.20.5 and later need Java 21, 1.18 to 1.20.4 need Java 17, 1.17 needs Java 16, and 1.16.5 and older run on Java 8). Compile. Each error is a name or a signature that changed; fix them one at a time, starting with registries and Item and Block constructors, which change most. Run the game, then fix what only shows up at runtime: data files and recipes.
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 migration notes for the new version from your loader.
- Raise the versions in gradle.properties and the mod metadata, and the Java version if needed.
- Compile and fix the errors from the top.
- Run the game and fix data files and warnings in the log.
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 1.21.5, Forge 1.17.1 to 1.20.1
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 1.21.5, Forge 1.17.1 to 1.20.1”Uses:
SharedConstants.getCurrentVersionWorldVersion.getName
This file only reads the version. The real work of an update is in your build files and the compiler’s errors; the steps list them.
src/main/java/com/example/examplemod/VersionCheckVersion.java
package com.example.examplemod;
import net.minecraft.SharedConstants;
// Version Check: prints which Minecraft version the mod runs on. After you raise the version in your build files, a mod that// compiles with no error here is on the new version; the errors the compiler shows next are the changes to make.public final class VersionCheckVersion { private VersionCheckVersion() { }
public static String minecraft() { return SharedConstants.getCurrentVersion().getName(); }}Fabric and NeoForge 1.21.6 to 26.3
Section titled “Fabric and NeoForge 1.21.6 to 26.3”Uses:
SharedConstants.getCurrentVersionWorldVersion.name
This file only reads the version. The real work of an update is in your build files and the compiler errors; the steps list them. Since 1.21.6 WorldVersion has name() instead of getName().
src/main/java/com/example/examplemod/VersionCheckVersion.java
package com.example.examplemod;
import net.minecraft.SharedConstants;
// Version Check: prints which Minecraft version the mod runs on. After you raise the version in your build files, a mod that// compiles with no error here is on the new version; the errors the compiler shows next are the changes to make.public final class VersionCheckVersion { private VersionCheckVersion() { }
public static String minecraft() { return SharedConstants.getCurrentVersion().name(); }}Forge 1.16.5
Section titled “Forge 1.16.5”Uses:
SharedConstants.getCurrentVersionWorldVersion.getName
This file only reads the version. The real work of an update is in your build files and the compiler’s errors; the steps list them.
src/main/java/com/example/examplemod/VersionCheckVersion.java
package com.example.examplemod;
import net.minecraft.util.SharedConstants;
// Version Check: prints which Minecraft version the mod runs on. After you raise the version in your build files, a mod that// compiles with no error here is on the new version; the errors the compiler shows next are the changes to make.public final class VersionCheckVersion { private VersionCheckVersion() { }
public static String minecraft() { return SharedConstants.getCurrentVersion().getName(); }}Forge 1.12.2
Section titled “Forge 1.12.2”Uses:
SharedConstants.getCurrentVersionWorldVersion.getName
src/main/java/com/example/examplemod/VersionCheckVersion.java
package com.example.examplemod;
import net.minecraftforge.fml.common.Loader;
// Version Check: prints which Minecraft version the mod runs on. After you raise the version in your build files, a mod that// compiles with no error here is on the new version; the errors the compiler shows next are the changes to make.public final class VersionCheckVersion { private VersionCheckVersion() { }
public static String minecraft() { return Loader.MC_VERSION; }}Sources
Section titled “Sources”- https://docs.neoforged.net/docs/1.21.1/gettingstarted/versioning
- https://docs.fabricmc.net/develop/porting/
- https://docs.fabricmc.net/develop/
Related how-tos
Section titled “Related how-tos”- Fix a wrong Java version error
- Publish my mod on Modrinth or CurseForge
- A config value players can change
- Add a game rule
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.