Troubleshooting Basics - XCOM-EU 2012
Most problems with XCOM mods are only resolved after ensuring you have complied with the standard knowledge articles for installing mods. When reporting a problem, expect to be asked if you have read and followed the following wiki articles. This resolves most problems, so indicating you have read these articles will speed the process of helping you along.
Then we need you to provide specific details such as Mod Name (a link to the download page is helpful), version if applicable, which XCOM game it's for (EU or EW, to include patch level), Windows Eventlog error messages (see below), or mod log files that occur after you have followed all of those steps. (Simply saying "it doesn't work" gives us nothing to work with to help you. If you can't re-create the problem in a reliably repeatable manner, it probably is hardware rather than software related.)
Programs and Tools
Basic troubleshooting of mod installation problems should not require any tools, but the "Required Reading" articles will make reference to, and require some from, the following article.
- Modding Tools - XCOM:EU 2012
- UPK Utils/PatcherGUI
The PatcherGUI tool (available from the UPK Utils download page) now (as of v5.2) includes options to "Enable INI loading" and "disable phoning home" for you. It can also find and open the correct config folder for you. So, to install INI modifications, one needs to select the correct game path (XCom or XCom/XEW), "enable INI loading" and "disable phoning home", and it will open the config folder and replace the vanilla file with the modified one. This is currently the recommended tool if you do not feel comfortable hex editing yourself.
- UPK Utils/PatcherGUI
Basic "Mod User" wiki articles, in order:
There are lots of "little things" that you have to "tweak" in those articles. Each and every one of them has been learned to be necessary the hard way. Don't try to skip any or take your own shortcuts. The articles cover why the steps are needed. While you can skip the "why" parts, taking the time to comprehend them enables you to understand what is likely going wrong in your current situation.
Be sure to report which mods (if any) you are using, and the last one you added or updated if more than one. Mod conflicts are to be expected (they are by different authors after all, and frequently make changes to hex code), but we need to know which are involved to know if there are known interactions. It is always best to install and test new mods in isolation (without any other mods installed, usually by having Steam "verify files") first to ensure they function correctly on their own in your setup. (Having a backup copy of your complete functioning modded game is a wise safety precaution anyway against the chance of a new game patch breaking everything.)
As the mod Long War (LW) is very popular, we'll use it as an example. Check the "Troubleshooting" document included in the mod package first. It has spawned it's own wiki page on the "ufopedia.org" site, so then check that wiki to see if things are "working as designed". (LW makes many hundreds of changes to vanilla XCOM code, affecting many fundamentals. It's almost a "new" game.)
Problems with LW (or any mod) while in a pre-release state are to be expected. Check in the Nexus forum XCOM File Discussions section for the specific Beta version "Feedback" thread. Note that only the latest Beta version will be supported. If you are having problems with an older Beta version the recommendation will be to update to the latest version to see if the problem has already be resolved.
Final release problems should be reported in the sub-topic on the Nexus download page, or as otherwise directed by the mod team in the included documentation.
Similarly, with other mods: re-examine the accompanying documentation carefully, including any "Read Me" files on the Nexus download page (which may be more recent than that in your package). In particular, note which version of the game ["Enemy Unknown" (EU) or "Enemy Within" (EW)] the mod was designed for, as this determines "where" you have to install the mod (number 1 cause of problems), and with which patch level  it was designed to be compatible. They are not interchangeable in general, and new XCOM updates/patches can make an older "offset" based mod immediately obsolete until the author updates it. Again, this has already been covered in the "Required Reading".
If the author has left the scene or abandoned work on the mod, you are on your own. Any easy way to check this is to look on the download page for the "last updated" date. If it is older than the release date for the latest patch level, it is likely to have problems.
For example, while "ToolBoks" (a mod utility) was very popular, the author never released the source code and has moved on to other games. That tool is obsolete, no longer available on the Nexus, and does not work with the currently patched game. A "downgrade package" for EU to revert to patch level 6 was created, which a specific release of ToolBoks is compatible with, but a "downgrade" package has never been created for EW. (Such "downgrades" require vanilla copies of the game files at both the old "target" and current patch levels. Without the forethought to preserve the "target" vanilla files, a "downgrade" package is not possible.) ToolBoks was never more than partially updated for EW and is also no longer compatible. No further work on ToolBoks is possible unless the author returns or releases the source code files.
More Specific Mod Help
Post your questions in the appropriate XCOM forum sections:
- XCOM Mod Talk - covers investigations into the vanilla game code.
- XCOM Mod Troubleshooting - intended for helping mod authors to get code working.
- XCOM Uploaded Files - related to specific individual mods found on the Nexus download site. Comments posted on the Nexus download pages show up here as well. Primary support area for individual mods (except "Long War").
- XCOM File Discussions - While open to discussion about any mod, this is the primary support area for the popular "Long War" mod. The Beta Feedback threads are located here.
The XCOM - Nexus Wiki is the repository of the community's collective knowledge about how the game functions and how to mod it. The articles are all developed by the community volunteers and do not reflect any official knowledge or position of the game's developers. The information is "organized" (such as it is) by "Categories". Start with "Category:0 Start here - XCOM", and the Navigating the XCOM Wiki article in particular.
This list assumes you have read the relevant wiki articles. It is merely an aid to reviewing the essential steps when ensuring you haven't overlooked one. It may seem redundent, but you have to start with ensuring the basics are all "correct" when troubleshooting.
- Move the game folder out of the C:\Program Files folder tree.
- If running Windows 8.1+ on new (post 2011) hardware, check if "Secure Boot" is involved if you need to exclude the game from DEP.
- Ensure the "phone home" feature is disabled in the "hosts" files (or equivalent).
- Check the \My Games\<Steam Game folder>\Logs\Launch.log file to verify this, or that a new IP address is not in use. Note that EU and EW use different IP addresses. You need to disable both sets.
- Restore the game to vanilla. This means both EU and EW. (If you are positive one modded version is fine, back it up and restore it later.)
- Re-enable the 'phone home' feature by commenting it out (begin each IP address line with "# ") for BOTH games, and disable it again after by removing the comment label ("# ") from the IP address lines.
- Test the restored game by running it up to the main "in-game" menu at least, twice.
- Wait at least 30 seconds between these attempts. If you still have problems, try rebooting between runups.
- Disable "hash checking" for EU. (EW no longer makes "hash checks".) The PatcherGUI mod now includes the ability to handle this for you.
- Remove/disable the "<filename>.uncompressed_size" companion files for any files you will be modding.
- Enable "INI loading". This is required for both EU and EW.
- Install the mod to the correct game folder (EW is in the sub-folder "XEW" under the <Steam install path> of .\Steam\steamapps\common\XCom-Enemy-Unknown\). So EU is under "\XComGame" and EW is under "\XEW", but they do share some (primarily video BLK) files. Unless it specifically says so, never assume a mod for EU will work with EW, or vice versa.
- If the mod requires you to locate a specific "offset" address within the vanilla file code, it will be specific to only a particular patch level of the game.
- If you have installed other mods prior to the one giving problems, it is possible one or more of them have caused the "offset" location to change. Try installing only the mod in question to eliminate possible mod conflicts.
- Check the Windows Eventlog for Application or System error messages.
([#] indicates the related "Required Reading" document.)
If your problem seems to be due to running out of RAM memory, see the wiki article 2-4GB game memory limits and solutions for possible solutions.
Windows Error Messages
Windows error messages only superficially look like they are saying 'the usual'. The details in the lower, large box are what are significant and do matter.
Typically a game or utility related error will be reported by the Operating System (OS) as an 'Event 1000, Application Error'. These "events" are found in the 'Administrative Tools | Event Viewer' tool under your 'Start' button | 'All Programs' folder. (Search online for 'windows event viewer' for more version specific details if you can't find it easily.) Note some elements are only visible when you are logged in with an Administrator privilege account. The "Event Viewer" has "filters" for types of errors that are presented as "Windows Logs". You should look at both the "Application" and the "System" logs for "Error" Level messages around the time your game had problems.
In particular the following details are of significance in these circumstances:
- 'Faulting application:' (probably '<game>.exe, version: <some numbers>, time stamp: <when occurred>')
- 'Faulting module name:' (very significant, the actual component source (exe/plugin/mod) of the error)
- 'Exception code:' (exactly what type of error)
- 'Fault offset:' (where in the faulting module the error occurred)
If any of the remaining lines of information seem pertinent, they should be given as well. In fact, the preferred method of conveying this information is a screenshot, but at least list the above data.
Referred to by this article:
- Modding Tools - XCOM:EU 2012
- Installing Games on Windows Vista+
- Steam and mods
- Basic Guide to installing mods
- Long War on Nexus
- Long War on ufopedia.org
- XCOM File Discussions
- XCOM Mod Talk
- XCOM Mod Troubleshooting
- XCOM Uploaded Files
- XCOM File Discussions
- XCOM - Nexus Wiki
- Navigating the XCOM Wiki
- 2-4GB game memory limits and solutions
That refer to this article: