Verified against the official NeoForge documentation and installer behavior for Minecraft 1.21.x, current as of October 2026. Java and version requirements can change with future NeoForge releases — check the official requirement before installing a new Minecraft version.
Most “NeoForge won’t install” threads aren’t installer bugs. They’re a Java version mismatch, and the installer’s own error message doesn’t say “wrong Java” — it says something cryptic like Could not find or load main class @user_jvm_args.txt. That’s the single most common failure, and it’s fixable in under two minutes once you know what’s actually happening.
Quick Start: Install NeoForge in 10 Minutes
- Check your installed Java version (
java -versionin a terminal) - Install Java 21 if you’re running 1.21.x, or Java 17 for 1.20.2-1.20.4 [2]
- Close the Minecraft Launcher completely
- Download the NeoForge installer for your Minecraft version from the official NeoForged site [1]
- Run the installer, select “Install client,” click Proceed [1]
- Reopen the launcher, create a new isolated profile pointing at the NeoForge version [1]
- Launch the profile once to generate the
modsfolder - Drop mod
.jarfiles into that folder and relaunch
Step 1: Get the Right Java Version First (Most Installs Fail Here)
NeoForge doesn’t bundle its own Java runtime the way the vanilla Minecraft Launcher does — you’re responsible for having a compatible JDK installed system-wide. Get the version wrong and the installer either refuses to run or produces a profile that crashes on launch. The requirement is version-specific, not “whatever’s newest”: Minecraft 1.20.5 and later, which covers every 1.21.x release, needs Java 21. Minecraft 1.20.2 through 1.20.4 needs Java 17 instead [2].
Run java -version in a terminal or command prompt to see what’s currently active [5]. If you’ve ever installed Java for another project, a different game, or a school assignment, there’s a good chance you have multiple JDKs on the same machine — and only one of them is on your system PATH at a time, usually whichever was installed most recently [5]. That’s the actual mechanism behind the installer’s @user_jvm_args.txt error: NeoForge’s own troubleshooting docs confirm it traces to an outdated Java version or a PATH pointing at the wrong install, not a corrupted download [3].
Download Java 21 from Eclipse Temurin (Adoptium) if you need it. One detail trips people up on the Windows installer specifically: “Add to PATH” is checked by default, but “Set JAVA_HOME environment variable” is not — you have to tick it manually on the custom setup screen [4]. If you’re not sure whether to bother, don’t skip it: some tools (including certain modpack installers) check JAVA_HOME directly rather than just PATH.
If a global PATH fix feels risky because you don’t want to disturb Java installs other software depends on, you don’t have to touch PATH at all. In the Minecraft Launcher, edit the specific profile under Installations, open More Options, and browse to the exact javaw.exe you want that profile to use. This is the safer fix on a machine running multiple JDKs side by side, since it scopes the change to one profile instead of the whole system.
If you’d rather install cleanly from a terminal instead of clicking through an installer, Windows users can run winget install EclipseAdoptium.Temurin.21.JDK and macOS users with Homebrew can run brew install --cask temurin@21 [5]. Both pull the correct 64-bit build directly, which sidesteps the 32-bit/64-bit heap space error covered further down.
Step 2: Download and Run the NeoForge Installer
Close the Minecraft Launcher completely before you start — the official docs flag this explicitly, and an open launcher is a common reason the new profile doesn’t show up afterward [1]. Grab the installer .jar for your target Minecraft version from the official NeoForged site, matching the version you checked in Step 1. Always grab the current installer build: versions 47.1.81 and earlier had a packaging bug that threw a Java security exception on launch, unrelated to anything on your system, that was fixed in later releases [10].
Run the installer. Confirm “Install client” is selected (not “Install server”) and click Proceed [1]. If the window never opens at all, that’s usually the installer trying to run without Java associated to .jar files — the Temurin installer’s default PATH association should prevent this, but if it happens, running java -jar followed by the installer’s filename from a terminal will launch it directly.
Step 3: Create a Launcher Profile and Confirm the Mods Folder
Open the Minecraft Launcher and go to Installations. Rather than using whatever default run option the installer added, create a new profile with its own name, select the NeoForge version you just installed, and — this is the part most guides skip — point it at a separate game directory outside the standard .minecraft folder [1]. That isolation means a broken modded install never touches your vanilla saves, and you can run multiple NeoForge setups side by side without them fighting over the same mods folder.
Launch the new profile once. A mods folder appears automatically inside whatever game directory you set. On Windows that’s typically inside AppData\Roaming; on macOS it’s under Library/Application Support, adjusted to whatever custom path you chose [7]. Anything you drop in there gets loaded on the next launch. For the actual process of sourcing, placing, and load-ordering mod files once the folder exists, our guide to installing Minecraft mods covers it in more depth than this setup walkthrough needs to.
Which Install Method Should You Use?
The official installer isn’t the only path, and which one fits depends on how you actually play. If you already know you want NeoForge specifically rather than Forge or Fabric, our Forge vs Fabric vs NeoForge comparison is the place to check that decision before you install anything.
| Method | Best For | Java Handling | Avoid If |
|---|---|---|---|
| Official installer + vanilla Launcher | New players wanting the simplest, most-documented path | Manual — you install and manage Java yourself | You’re juggling multiple modded instances on different MC versions |
| CurseForge App | Casual players who want mod browsing and profile switching in one UI | Still requires a compatible system JDK; the app doesn’t install Java for you [7] | You want full control over installer flags or a non-standard game directory |
| Prism Launcher | Hardcore users and completionists running many instances with per-instance Java overrides | Built-in Java Wizard picks and manages Java per instance automatically | You’re on NeoForge 1.21.7 specifically — a “Unable to detect the forge installer” failure has been reported on that exact combination, traced to an upstream ForgeWrapper component rather than Prism Launcher itself; check you’re on the latest Prism build before assuming it’s a Java problem [8][9] |
Common NeoForge Install Errors, Fixed
These are the exact error strings from the official troubleshooting docs and installer bug reports, not paraphrases — search for the bracketed text if you’re troubleshooting mid-install.
| Error / Symptom | Cause | Fix |
|---|---|---|
| “Could not find or load main class @user_jvm_args.txt” | Outdated Java, or PATH pointing at the wrong JDK when multiple are installed [3] | Update to Java 21 (or 17 for 1.20.2-1.20.4); on Windows run Jarfix, on macOS/Linux reset JAVA_HOME and PATH [3] |
| Installer window never opens | Java not associated with .jar files | Run java -jar [installer-name].jar from a terminal, or reinstall Java with the PATH/association option checked [3][4] |
| “java.lang.OutOfMemoryError: Java heap space” | 32-bit Java installed instead of 64-bit | Uninstall 32-bit Java, install the 64-bit Temurin build [7] |
| New profile missing from the launcher after install | Launcher was still open during installation [1] | Fully close the launcher, then rerun the installer |
| SecurityException / “no manifest section for signature file entry” | Outdated installer build (47.1.81 and earlier) [10] | Redownload the current installer from the official site |
| Black screen or crash immediately on launch | GPU driver issue, or the early-display window conflicting with your setup [3] | Update GPU drivers; if it persists, set earlyWindowControl=false in config/fml.toml [3] |
FAQ
Do I need Java 21 no matter which Minecraft version I’m modding?
No — and installing the newest Java “to be safe” is exactly the wrong move for older versions. Only 1.20.5 and later (all of 1.21.x) needs Java 21; NeoForge on 1.20.2-1.20.4 specifically requires Java 17, and running a too-new JDK there can cause the same PATH-conflict failures this guide is built around [2]. Match the version to your target Minecraft release, not to “whatever’s latest.”
Will installing a second JDK break my existing Java setup?
Not if you use the per-profile Java executable override instead of relying on a shared system PATH. Multiple JDKs coexisting is normal and expected once you’re modding across several Minecraft versions — the mistake is assuming the launcher will automatically pick the right one for each profile rather than pointing it there explicitly.
Does the CurseForge App remove the Java version problem entirely?
No, and that’s worth knowing before you pick it for that reason. It manages the NeoForge profile and mod downloads for you, but it still calls whatever JDK is on your system — if that’s the wrong version, you’ll hit the same errors as a manual install, just inside a different UI [7].
Why does my launcher still show an old Java version after I install a new one?
Because installing a new JDK doesn’t retroactively fix a launcher profile that’s already pointed at a specific javaw.exe path, and a system PATH update only affects tools that read PATH fresh at launch. Check the profile’s Java Executable setting directly under More Options rather than assuming a new install propagates everywhere.
I mod both a 1.20.4 pack and a 1.21 pack — do I need to keep switching Java versions?
No, and this is exactly the case the per-profile override exists for. Install both Java 17 and Java 21 side by side, then point your 1.20.4 profile’s Java Executable at the 17 install and your 1.21 profile at the 21 install. Neither profile touches the other, and you never have to uninstall or reinstall Java when switching between packs.
Once the profile launches clean, the mods folder is the only thing left to fill. Our list of the best Minecraft mods in 2026 is a solid starting point if you haven’t picked any yet.
Sources
- NeoForged Docs — Installing a NeoForge Client
- NeoForged Docs — NeoForge User Guide
- NeoForged Docs — Troubleshooting & FAQ
- Eclipse Adoptium — Windows MSI Installer Documentation
- Minecraft Wiki — Tutorial: Update Java
- NeoForged GitHub — Installer SecurityException Issue #740
- CurseForge Blog — How to Install NeoForge in Minecraft
- Prism Launcher GitHub — Forge Installer Detection Issue #3924
- Prism Launcher Wiki — Creating an Instance
I've been playing video games for over 20 years, spanning everything from early PC titles to modern open-world games. I started Switchblade Gaming to publish the kind of accurate, well-researched guides I always wanted to find — built on primary sources, tested in-game, and kept up to date after patches. I currently focus on Minecraft and Pokémon GO.