publieople Minecraft Modpack Startup Hang Diagnosis
When a Forge modpack client hangs during startup without crashing, the cause is almost always at a specific phase. This skill covers triage and binary-search diagnosis using PCL2 logs.
When to use
- User reports: "卡住 / hang / stuck at loading / 不进主菜单 / 启动卡死"
- Splash screen sits forever, no crash dialog, no error
- User has already tried disabling the most recently added mods (strong signal their correlation is wrong)
First pass — extract evidence before hypothesizing
Locate logs
PCL2 (most common on Chinese desktops) writes to the version directory:
E:\.minecraft\versions\<versionName>\logs\
debug.log # full binary-ish, use `strings`
latest.log # human-readable tail
debug-1.log.gz ... debug-5.log.gz # rotated boots
HMCL / MultiMC use similar structures under their own roots.
Three facts in order
1. Actual Java version used — not the launcher's preference:
strings "<gameDir>/logs/debug.log" | head -3 | grep "java version"
Then cross-check with %AppData%\PCL\config.json → JavaList[]. PCL2 default-uses java-runtime-delta (Java 21) even when the version JSON declares java-runtime-gamma (Java 17). The user setting may not match the running version.
2. Hang phase — tail -c 5000 of debug.log:
tail -c 5000 "<gameDir>/logs/debug.log"
Look for the ModernFix 60s worker shutdown signature — if you see Worker-ResourceReload-N shutdown lines at exactly 60s intervals with no [Worker-Main/INFO] Setting up or Loaded X mods between them, the hang is in the resource reload listener completion phase. This is the most common Forge 1.19.2 hang location.
3. Verify user-claimed mods are actually loaded this boot:
strings "<gameDir>/logs/debug.log" | grep -ciE 'modname1|modname2|modname3'
If 0 hits, the mods were never loaded. PCL2 / CurseForge convention: .jar.disabled = skipped, zero log noise. The user's "I disabled them and it still hangs" is actually "they were already not loaded", which means the hang is somewhere else — almost certainly in pack-bundled mods the user never touched.
Hang signature → likely suspects
If silence starts after Reloading ResourceManager: and 60s ModernFix shutdowns follow, the culprit is one of these reload listeners:
| Phase | Suspect | Verify |
|---|---|---|
| Late ModelBakery / TextureAtlas | corrupt PNG inside a mod jar | grep Could not load image: Corrupt PNG near the silence |
| KubeJS asset regeneration | ponderjs-*.jar (Create ponder scene generator) synchronously re-emits JSON during reload |
ls kubejs/assets/ponderjs_generated/ (if present, suspect); grep [KubeJS/]: Found plugin source ponderjs in log |
| Shader pack init | oculus-*.jar + embeddium-*.jar combination (known: Asek3/Oculus #691) |
both jars present + shaderpack selected |
| ModernFix cache wait | modernfix-forge-*.jar with mixin.perf.dynamic_resources=true |
grep modernfix-mixins.properties for that key (default false) |
| Resource reload deadlock | Create + huge config; farmersdelight + create_central_kitchen mixin targets not satisfied |
grep Mixin target ... was not found for missing classes |
Binary search via .disabled
PCL2 / CurseForge convention: rename mods/<mod>.jar → mods/<mod>.jar.disabled to skip it.
- Start with the suspect the evidence table points to, NOT the user's mods — those were already tried.
- Disable one → restart → observe:
- Hang time shortens or game enters main menu → that mod contributed, narrow in
- Hang signature identical → wrong mod, re-enable, try next
- For PonderJS specifically:
mods/ponderjs-1.19.2-*.jar→.disabled. If game enters main menu, that's the hang. - For embeddium+oculus: disable
oculus-*.jarfirst (o is the higher-risk side); if still hangs, disableembeddium-*.jar.
Anti-patterns
- Don't trust Java version blame without verifying the actual launched Java. Java 21 → 17 switch only helps if the pack needs Java 17 module exports. For resource reload hangs, Java version rarely matters — verify with the
strings | grepabove before recommending the swap. - Don't recommend disabling the user's mods first. They were already tried. The hang is likely in pack-bundled mods.
- Don't suggest multiple changes at once. Each test's diagnostic value vanishes if 3 things changed.
- Don't ask for a thread dump. This is a Windows client, no easy jstack path from WSL, and the 60s ModernFix signature already localizes the phase.
- Don't recommend RAM increases for this signature. The hang is not GC pressure, it's a listener never returning.
Verification of fix
After removing the culprit, the boot should show:
[Render thread/INFO] ... Reloading completeor[main] Setting up ... MainMenuScreen[main/INFO] ... Loaded X mods
If the user reports "still hangs after disabling X", binary search continues. The signature (60s cadence) stays the same only if the wrong mod was disabled.
Reference
See references/forge-1192-hang-signatures.md for exact log strings to grep for and a worked example.