What to do when the game crashes
The crash window itself usually does not show the cause. GPCL reads the logs first to provide clues, then work through the order below.
Click "Export error report" in the crash dialog and save the generated zip. The report starts with GPCL's analysis, followed by the mod list, Java, launch arguments, and all logs; troubleshooting mostly relies on it.
1. Read GPCL's analysis first
The dialog shows 1-2 clues GPCL found in the logs, such as "out of memory" or "mod dependency or compatibility check failed". Click "View details" to see all clues, the corresponding log lines, and the crash information.
These conclusions come from keyword matching and are only a direction to investigate. When the logs contain something more specific (such as which dependency is missing), it is listed among the evidence as well.
2. Export the error report
The button is right in the crash dialog. Pick a location and GPCL packages:
error-report.txt: analysis results, error summary, system / GPU / Java, mod list, resource packs and shaders, launch arguments, game output, error lines from the logs;crash-reports/: crash reports generated by this crash;logs/:latest.loganddebug.log(only the tail is kept when they are too large);jvm-crash/:hs_err_pid*.logwritten by the JVM itself (when a GPU driver problem or similar crashes the JVM);launcher-log.txt: the launcher log;game-output.txt: standard output and error output from this run of the game process.
--accessToken and the system username in the report are masked, so it can be sent as is. Do not send only a screenshot of the crash window.
3. Look at the log yourself
"View log" in the dialog opens the game process output. Focus on the very bottom, and search for these words:
| Keyword | Usually means |
|---|---|
Exception, Caused by | The real exception is usually after the first Caused by |
OutOfMemoryError | Not enough memory allocated |
UnsupportedClassVersionError | Java version does not match the game version |
NoSuchMethodError, ClassNotFoundException | The mod does not match the game or loader version, or a dependency is missing |
GLFW error | A problem with the GPU driver or OpenGL support |
4. Common causes
| Symptom | Common cause | What to do |
|---|---|---|
Exits right after launch, with UnsupportedClassVersionError in the log | Wrong Java version | Let GPCL install Java automatically, or switch the mirror in settings and reinstall |
Freezes or closes halfway through loading, with OutOfMemoryError in the log | Not enough memory, or too many mods | Raise the allocation under Settings → Game → Memory allocation; do not exceed physical memory |
| Crashes while loading mods, with mod names in the log | Wrong mod version, missing dependency, or two mods conflicting | Try that mod alone first; check the MC version and loader version it supports |
Exits before the window appears, with GLFW error | Outdated GPU driver, or no OpenGL support | Update the GPU driver; on a laptop, make sure the game uses the discrete GPU |
Kicked from a server with Invalid session | The sign-in state expired, or the account does not own this version | Sign in with the Microsoft account again; confirm the account really owns the version |
| Crashes when entering a world or loading a resource pack | A world, resource pack, or shader pack is corrupt | Try a new world first; back up the world before working on it |
Crashes on startup with Fabric, reporting missing fabric-api | Fabric API is not installed | Check "Install Fabric API as well" when reinstalling Fabric, or install it manually |
5. Rule out these three first
- Turn off all mods, resource packs, and shaders, then start once bare. If it works, the problem is in the mods.
- Start a vanilla version instead. If it works, the current version or its mod combination is the problem.
- Create a new world. If it works, the old world is broken.
6. Still not working
Email gamets@caellab.com with the exported error report, and also state:
- launcher version, Minecraft version, loader version;
- which mods are installed (version numbers help);
- what you did before the crash.
"it crashes on startup" alone is very hard to diagnose; the logs in the report are what matters.