| # 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. |
|
|
