Reporting Bugs
So, you found a bug... it happens, especially in betas.
Before you decide to report a new issue or start a dialogue in the Discord chat, please read the following guidelines.
I (focustense) want EasyNPC, and any other apps created under the EasyMod moniker, to be convenient, performant and generally trouble-free. I would love to see these projects become "go-to" modding tools like Synthesis, or zMerge, and in order to achieve that, they need to be very stable and reliable, if not perfectly so. Therefore, I want to get bug reports, no matter how seemingly small or trivial. Reporting just one bug can make life better for dozens or hundreds of other users.
Having said that... modding a Bethesda game is not a point-and-click, drag-and-drop adventure. Most people can install a few dozen mods following a step-by-step guide and still end up with a working game. Expanding into the hundreds or thousands of mods requires deeper knowledge and more experience. Just as one should not expect to be able to run a marathon after their first few jogging sessions, one should not expect to be able to build a correctly-functioning modded Skyrim build with 1200 mods after experimenting for a few weeks with 50 mods. The difference in scale is profound.
This is a roundabout way of saying that:
- Bug reports that clearly highlight a problem with EasyNPC (or other EasyMod properties) are welcome and encouraged.
- However, this is not an offer to help with "general modding troubleshooting".
- Just because you happened to be using EasyNPC, does not mean the problems with your game are because of EasyNPC.
- If you are running a complex setup, and experiencing problems in the game, then it is up to you to establish the connection between what the app has generated and how it is affecting the game.
Tech support is a necessary and valuable part of any real-world product and you should not hesitate to ask if you need it, but please be sure you are asking the right person, in the right context. If the car you just bought starts making funny noises, you call the dealer or a mechanic; if the car is wrapped around a tree, you call insurance.
With all disclaimers out of the way, to get the best (fastest, most helpful) response for your particular issue, you should decide what category your issue falls into, and follow the respective guidelines for that category.
An app crash can either be an explicit crash message:
Or - much less commonly - it can be the app shutting down suddenly without any warning. These two situations might seem different, but they are fundamentally the same thing.
If you've experienced a crash:
- Find your log file or event log entry
- Start a new issue
- Attach your log file or exception text, either directly or by linking to a pastebin, pasteboard, etc.
Logs/traces are required for crash reports. Unless it is very widespread and affecting a large number of users, crash reports that are missing a crash log will probably be closed as no-repro.
EasyNPC creates a new log file each time you run the app. If you've experienced a "soft" crash, with a visible error message, then that message will tell you exactly where the file is located and what it is called:
Simply click on the link, and scroll to the file with the specified name.
If you did not get a visible error message, and the app simply shut down, you can still open the EasyNPC data directory from any Windows Explorer window. Type the exact text %LocalAppData%\EasyNPC into the address bar, and press Enter or click on the arrow.
The log file you are looking for will be the last (or most recent) file starting with Log_.
ℹ️ Log files are named after the date and time you ran the app, in the format YYYYMMDD_hhmmss. The log file named Log_20211010_145346_2459675.txt above indicates that the app was started on October 10, 2021, at 14:53:46. The last field (2459675) is microseconds.
|
If for some reason you don't see any log files in this directory, or your most recent log file isn't showing any error at the end - you'll know it when you see it, by way of the text [ERR] Exception was not handled - then you may need to get the crash info using the alternative (event log) method below.
Crashed without any error and don't see anything interesting in the log file? No problem - you can still get this information from the Windows event log.
NOTE: This method gives less information about the crash than a full log file, so please only use this if you can't get a log file or if the log file isn't showing any information about the crash.
First, open the Windows Event Log viewer by starting to type "event viewer" in the Windows run box. You'll normally see it after the first few letters.
Click on the "Event Viewer" app, and in the window that pops up:
- Expand "Windows Logs"
- Click on "Application"
- Scroll down until you see an entry that says
Errorunder "Level", and.NET Runtimeunder "Source".- You can speed up the search by clicking on
Filter Current Log...on the right side, and checking theErrorbox next to "Event level".
- You can speed up the search by clicking on
- Click on the entry, and in the text box below, make sure that the first line says
Application: EasyNPC.exe. If it refers to any other application, then keep going down the list until you find one referencing EasyNPC. - Copy the entire text in the text box, and paste it into your bug report, preferably in a code block like this:
``` (paste here) ```
Your message won't look exactly like the one above, but as long as it says Application: EasyNPC.exe at the top, it's the right one.
If the app isn't crashing, but is doing something that doesn't make sense or is just surprising or unexpected, then a log file may not be very useful. What's most important for these types of bugs is reproducibility, i.e. someone else can take your report and make the same bug happen on their system.
To give other people the best possible chance of reproducing the bug, try to do the following:
- Repro yourself on a minimal profile (mod list/load order). If one or two specific mods must be installed in order to repro the issue, that's great - no problem and please note this on the report. However, if we have to install 500 mods to try to replicate your exact configuration, the report will probably be ignored.
- Make sure the issue is repeatable. It's still good to file a bug for issues that are somewhat intermittent, say half the time or even 1/3 of the time. However, if it takes 20 tries on average, then it's low priority.
- Eliminate redundant or unimportant steps. For example, if clicking on a particular button always makes blue smoke spew out of your machine, no matter the circumstances, then you should not include all of the things you did before clicking it.
The above are suggestions, but please try to do them, to the best of your ability and in a reasonable amount of time. The idea is not to make you spend 3 hours trying to isolate the exact cause of a bug, but rather to get you to spend 5-10 minutes narrowing it down a little bit, so that we don't have to spend 3 hours chasing down wild guesses.
A good bug report in this category does not need to be incredibly detailed. Simply include each of the following:
- What you were doing at the time (steps to reproduce)
- What you expected to happen
- What actually happened
If the app itself is working fine, but you're seeing problems with the output it's producing - that is, the .esp or .bsa files - then you'll want to create a more technically-oriented bug report.
First, please try to narrow down the problem to the minimal set of mods/plugins required, if you haven't already. This should be easy if you pick one specific NPC who is exhibiting the problem, and then generate a new merge using only that one NPC's chain of Default and Face Plugins. Exclude any mods that add a lot of NPCs, like Falskaar or Interesting NPCs, unless they are specifically relevant to the problem.
If the undesirable output is in the EasyNPC plugin (NPC Appearances Merged.esp), then a great report will include:
- A table or screenshot of the relevant parts of the records in xEdit, including both the EasyNPC plugin and any plugins that it was supposed to have referenced/merged
- A screenshot of your profile entry for the affected EasyNPC showing their plugin selections, or a copy of your
Profile.logfile along with the editor ID/form ID of the NPC - A copy of your minimal-repro
NPC Appearances Merged.espplugin, if possible - An explanation of why you consider the output incorrect, and/or what specific problems it is expected to cause.
If the plugin is fine, but something appears to be wrong with the assets, then please include:
- Name/URL of the mod containing the original assets
- A zip containing the broken assets, or, if they are too large to attach or are missing entirely, then a list of the paths to these assets
- If the problem is with a facegen file and you can't include the file itself: two screenshots (or one side-by-side) from a tool such as NifSkope showing the expected (e.g. original) and actual meshes
- A general explanation of the problem and/or the negative effects it has.
As with UI bugs, the above are "strong suggestions". If you can't include some of the information or if it would be excessively time-consuming to do so, then don't - but please be respectful of developer time and be willing to spend an extra 5-10 minutes in order to save us several hours.
If you are having problems with an EasyNPC mod in the game, but can't find anything specifically wrong with the plugin or its assets (or don't know how or where to look), then this is where things start to get dicey.
Experience has shown that fewer than 1 out of 10 issues, and probably more along the lines of 1 out of 100, have anything to do with EasyNPC. These bugs can happen, but with more than 15k users (as of Oct 2021), virtually all of these issues have been discovered and fixed by this point.
It's possible that your NPC bug is really the result of a bug in EasyNPC. But it is not likely. The breakdown of issues is roughly:
- [85%] Not following the basic instructions, particularly with regard to disabling original overhauls at the end of the process, and avoiding visual overhauls and their respective patches in the Default Plugin setting.
- [5%] Conflicts with another tool or patcher (Wrye Bash, Synthesis, etc.), in particular when these patchers are run with the EasyNPC mod disabled or plugin inactive, subsequently creating conflicting records.
- [5%] Conflicts with follower mods, quests/expansions or other "new NPC" mods that aren't supposed to be disabled afterward, but which provide their facegen data as loose files.
- [3%] Conflicts with mods that make major changes to vanilla races or head parts, which tend to be incompatible with all NPC replacers.
- [1-2%] Actual problems with EasyNPC's build system.
Moreover, regardless of whether an issue is part of the 2% bugs or the 98% not-bugs, attempting any serious investigation of it sucks up a lot of time that could be spent fixing other bugs or adding new features, because it requires several rounds of trial and error to learn all about your specific game build and what might be conflicting.
Therefore, reports of in-game issues will not be looked at or accepted as bugs unless they are accompanied by clear evidence of an error in EasyNPC's build output. In other words, unless it can be presented and proven as a build output problem.
If you are struggling with in-game issues, first use the Post-Build Checker, which resolves the majority of conflicts, and if that does not solve your problem, try the Troubleshooting Guide. Questions about in-game issues in the Discord chat will generally be referred to these two resources.
Questions, ideas, feedback and any other EasyMod-related topics of discussion are always welcome in the Discord chat. You can also start a GitHub discussion if you're looking for something that is more visible or will last a little longer.
Feel free to ask tech support questions on the Discord chat as well - keeping in mind that these guidelines still apply, especially the ones about in-game issues.
Some items are very common to see in bug reports, despite not being helpful at all. Please do not include any of the following:
- Multiple bugs in the same report. Even if you think they're somewhat related, it's much easier to mark one as a duplicate of the other than it is to try to disentangle two unrelated issues submitted as one.
- A list of all the affected NPCs. If the problem cannot be identified or solved by looking at one single actor, then it is likely not a problem with EasyNPC in the first place. Either that, or it is multiple issues (see previous point).
- Speculation about the cause of the problem. 99% of the time it is incorrect and wastes everyone's time. The exception to this is a verified build output problem, in which case the "cause" is the "problem" being reported. However, speculation based on random guessing/experimentation will get your bug resolved slower, not faster.
- A list of all the mods you're using, or the ones you think are involved (see previous point).
- Crash reports from DotNetScriptFramework, SKSE, Papyrus logs, or other in-game debugging artifacts. EasyNPC runs outside the game, everything important about the way it's behaving can be deduced from its output, and this is not a place for general modding troubleshooting.