modding-model/skill/modules/log-debugging.md

log-debugging

How to read a game's error log, find the root cause, and verify the fix. Use after every launch attempt.

Method

1. Ask the user to launch the game once and give you the newest log path (or find it from the game's module). Use grep_file on the log for ERR|ERROR|Exception|has not met|missing|Cannot|FATAL|Could not load before reading whole files; use read_file with tail for the end (crashes) and with start for specific regions.
2. Collect ALL missing-dependency / missing-file messages first. They are usually the root cause. Fixing them clears most downstream errors.
3. Separate cascade from root: an exception while loading mod X usually repeats a missing dependency reported earlier. Read the underlying "Could not load file or assembly / dependency" line.
4. Separate noise from real: "cannot resolve" lines for things that load fine later are noise. A "cannot resolve" for something absent from the loaded-DLL/mod list is real.
5. Check the disk: list the mod folder with list_dir. A mod folder that exists but lacks its own library/API file means a partial deploy (failed extract, antivirus quarantine, manager error): reinstall that mod and verify the file.
6. Look up unknown errors with web_search (exact message in quotes + game name + mod name). Prefer the mod's GitHub issues or official docs.
7. Fix the root cause only, then ask for a fresh log and re-check. Repeat until clean. Record every problem with tracker_note kind issue (with severity), mark it resolved when fixed, keep the stage on debug, and list remaining warnings in the tracker.

One worked example (a KSP log; the method is the same for any game)

• AssemblyLoader: Assembly 'X' has not met dependency 'Y' appears right after "Loading assemblies": root cause. Example: Kopernicus not meeting ModularFlightIntegrator.
• Exception loading 'Parallax' ... Could not load file or assembly 'Kopernicus': cascade from the line above.
• ADDON BINDER: Cannot resolve assembly: USIToolsUI: noise if USIToolsUI appears later in "Mod DLLs found". Cannot resolve assembly: Kopernicus is real (confirms the root cause).
• Cannot create config from file / Empty part config file: empty or unparseable file; harmless unless it is a part config.
• contains an unnamed node. Skipping: a hand-written patch has a brace block with no node name; that patch is not applying; open the file and find the nameless {.

Severity

will-crash (game will not start or load a save) > feature-broken (mod does not work) > cosmetic (warnings that change nothing). Fix in that order and say which is which.