skill/modules/ftb-debugging.md

ftb-debugging

FTB/NeoForge modpack crash debugging: Phase 5b crash triage, config traps, cascade crashes, version mismatches, Crash Assistant, mod-page-first rule.

Config persistence trap

Some mods write config files on first launch. If that config is malformed or conflicts, the game refuses to load even after you disable the mod's jar — until you clear the configs folder. Always grab the crash log BEFORE clearing configs. The config folder is evidence.

Strategy: regenerate a clean config baseline by launching with zero added mods, then re-enable mods one at a time.

Reading crash reports — priority order

1. Crash Assistant log (if present) — often names the culprit directly. Look for Shown KnownCrashReason: at the bottom.
2. crash-*.txt in crash-reports/ — the Caused by: line is usually the real error. Read the full stack before the mod list.
3. latest.log — grep for ERROR, Exception, Caused by, Failed to load, Unknown registry key.

Cascade crashes

A crash during registry loading (world creation, not FML startup) can make an innocent mod appear guilty. Example: one Create addon failing during RegistryDataLoader triggers Unknown registry key errors in Forbidden Arcanus's ritual files — Forbidden Arcanus is the symptom, not the cause. Always trace back to the earliest error in the log, not the most visible one.

Mod-page-first rule (MANDATORY)

When you identify a specific mod as the culprit, do not skip this:

1. Find the mod page (CurseForge or Modrinth first, then GitHub)
2. Read the full description — developers document known crashes, Sodium/shader compat issues, and config workarounds here
3. Check the changelog across recent versions
4. Check open/closed GitHub issues for the exact exception class or error string
5. Only then recommend: config fix → version update → remove as last resort

Example: mekanismcovers crashes with a Sodium mixin failure (SodiumBlockRendererMixin). The mod page documents this as a known issue with a config variable fix — not a removal situation.

Common version mismatch patterns

• Companion mod tight versioning: Some mods require an exact version of a sibling library. Wrong version = NoSuchFieldError or ClassNotFoundException at FML load.
• Addon built against old parent: An addon for Mod X may have been built against an older version than what's installed.
• Mixin failures: Mods that inject into renderer or engine classes (Sodium, Iris, etc.) break when the target API changes. Check the mod page for config fixes before removing.
• Duplicate jars: Adding a new version without removing the old one leaves both in the mods folder. NeoForge/Forge may silently load the wrong one or crash. Always check for two jars with the same mod name.

NeoForge / FTB specifics

• FTB modpacks are NeoForge-based. All added mods must be NeoForge builds for the correct MC version.
• Create version split: Create 5 (0.5.1.x) and Create 6 (6.0.x) addons are not cross-compatible. Confirm which Create version the pack ships before adding any Create addon. Crash Assistant flags this as Create6Addons.
• Installing a Forge mod on a NeoForge instance (or vice versa) — silent fail or FML crash.