Modded Minecraft Self Help Guide

Preamble/Intro

This guide is made to help players who have a problem with modded Minecraft by providing explanations for probably causes of common kinds of problems, and linking to other tools and websites where appropriate.

To use it, first navigate to the section relevant to you. You can do this by clicking the buttons that match your problem, using your browsers "search in page" feature, or by some combination of those two.

If you have questions or improvement ideas about this guide, please create an issue or make a pull request on the repository where this file is hosted: https://github.com/McModknower/McModknower.github.io/.

Some quick links for people who roughly know what they need: Crash Database, Usual Suspects

What kind of problem do you have?

A Crash

Without you killing mc, it closes by itself. Maybe your launcher shows some kind of error message. If you have the Crash Asisstant mod, its window opened.

A Disconnect

Minecraft started and you tried to connect to a server, but then you got some error message and got back to the multiplayer/server selection screen. (If your game crashed when trying to connect, click "A Crash" instead of this one.)

A Freeze

Minecraft stopped responding. You can't move, and waiting for 5 minutes doesn't change anything. Maybe your OS shows you a dialog similar to "Minecraft stopped responding. Force close it?"

Lag

Minecraft works, but you have low FPS/TPS, mobs move slowly/only a few times per second.

Mod Feature

Some mod feature is not working as you think it should. Maybe a machine is not receiving power, some mob is not attacking as it should.

Other Stuff

Something else not mentioned in another option.

What information do you have about the crash?

Crash Report

You got some file with a name like crash-2026-02-30_12.34.56-client.txt and/or starting with ---- Minecraft Crash Report ---- in the crash-reports directory.

JVM crash report

You got some file with a name like hs_err_pid1234.log and starting with # A fatal error has been detected by the Java Runtime Environment: in the instance/game directory (aka .minecraft).

latest.log

You got a file named latest.log or have a launcher that shows you the log directly (MultiMC, Prism Launcher, ...). It is normally a few megabytes in size and starts does not start with one of the things named in the other file types.

I don't know

You have no idea what a crash report or jvm crash report is, and if you have one for the current crash.

What do you see on the disconnect screen?

TODO

So you have a Freeze

Watchdog crash/log

You got something in a crash report or latest.log about the watchdog. It nomally looks like this: java.lang.Error: ServerHangWatchdog detected that a single server tick took 60.00 seconds (should be max 0.05)

java.lang.OutOfMemoryError

Your latest.log contains something about java.lang.OutOfMemoryError

Neither

You have no useful information in the latest.log and no watchdog crash.

What to do with a Minecraft crash report

TODO

What to do with a JVM crash report

TODO

What to do with a latest.log

TODO

How to find the relevant log/report files

TODO

So you have a lag problem

TPS vs. FPS Problems

To be able to properly diagnose your problem, you should be able to differentiate between server/TPS lag on the one hand and client/FPS lag on the other. In addition to these descriptions here, you can also use your F3 screen (see next subsection) to figure out what kind of lag you have (if you can open it).

If you have only Server/TPS lag, the mobs and machines on the server are slower than normal. If you are riding a minecart/horse/pig/whatever you might not be able to dismount, or it might take some more time.

Client/FPS lag means your screen is stuttering, you get noticeably less frames. Sometimes people also call it a slideshow, especially if you get only 1-2 frames per second or less.

Using your F3 screen & Task manager

Your F3 screen shows some values that are interesting for debugging lag problems: The FPS: if this is below 30, you have Client/FPS lag. The TPS and MSPT: if TPS is below 20, or if MSPT is above 50 you have Server/TPS lag. The Memory/RAM allocation and usage: If the used memory is close to 100%, you should allocate more ram to Minecraft or have less stuff.

Your Task manager is also helpful. If your task manager shows that your system ram is nearly fully used, you should allocate LESS ram to Minecraft or close some programs you don't need. If your task manager shows that your system cpu is nearly fully used, you can either continue following this guide to find lag problems inside Minecraft, or close some cpu using programs you don't need.

laggy datapacks

First, remove known sources of lag: Any datapack (or datapack packaged as mod) that checks entity nbt, for example to provide dynamic light. Datapacks i know that do this: dynamiclight, enchantments_plus, origins_plus_plus, incendium. (Note: lambdynlights is a client-side mod that provides dynamic lighting, and does not fall under this rule)

GPU heavy visual mods

Some visually heavy mods can cause FPS problems if used too much. Any shader or lod mod falls under this, namely iris, distant horizons, voxy, and bobby.

Making a spark report

If you still experience lag after doing the steps above, its time to make a spark profiler report. After installing the mod, you can use /spark profiler start --timeout 50 to start a profiler that records stats about the cpu usage of the server thread for 50 seconds. Since it profiles the server thread, it is useful for tps problems

What to do with a Watchdog crash

TODO

What to do when you got an OutOfMemoryError

TODO

Making and interpreting a thread dump

If your game froze, and you have no other leads, a thread dump is the most viable option to get more info. It dumps what the code is currently doing, so if it is stuck on one specific thing, it will be listed inside here. If you have modernfix installed, you can enable its spamming thread dump feature by adding a new line with mixin.feature.spam_thread_dump=true to the end of the modernfix-mixins.properties config file. This makes a thread dump in regular intervals. Do the config changes, then restart your Minecraft, trigger the issue again, wait for 2-3 minutes so the problem gets dumped. If that modernfix config option is not working for you (no modernfix in your pack, modernfix conflicting with some other mod, ...), create one using one of the methods described on https://www.baeldung.com/java-thread-dump. Then look into the file and search for the stack traces following "Server thread" and "Render thread". Sometimes when you loaded into a world, but something went wrong during crashing, "Server thread" is no longer there and you need to look for the last time Server thread appeared normally in the log. Maybe there is some mod mentioned there, but reading them is always advisable. If they contain something about .getChunk, this indicates they are currently getting/loading/generating a chunk. In that case looking into the worker threads "Worker-Main- is also a good idea.

Mod specific problems

If you have a problem with a feature/bug in one specific mod, check the mods bug tracker and wiki, or ask on its discord, if these things exist for that mod. Normally mods have linked these on their mod download page on modrinth/curseforge. See the following two screenshots for where they can be (using Crash Assistant as an example):

Other things

Since this website can't list every single problem and what to do, here are some general modded mc problem solving tips: