Mod troubleshooting

Troubleshooting is the identification of the cause of crashes, bugs or other problems.

Overview

In general there are two kinds of errors: fatal and non-fatal.

Fatal errors occur when the game cannot load a vital piece of data and cannot operate without it present. This causes a crash to desktop (CTD). When fatal errors occur, an exception will be printed to the exceptions.log. Typically these errors occur during the loading process or when a specific action is taken in game.

Non-fatal error occur when the game encountered invalid data or broken syntax. These errors are almost always printed to the error.log.

Testing

Performing testing is vital to debugging a mod. Typically this is done via the in-game console with commands such as event, observe and run.

The run command is very useful for testing effects without having to reload the game. It also makes it very easy to setup test scenarios without introducing wayward code within the mod itself.

The observe is useful when you want to test the stability of your mod during gameplay. By becoming an observer, you can let the game run without your input, making it easier to detect issues that occur irregularly.

Loading

When launching the game the following steps occur:

Step
Loading Databases
Initializing Maplogic
Loading Databases...
Loading History Files...
Loading Sounds...
Loading Events...
Loading GUI Definitions...
Loads Flags...
Creating Checksum...
Loading Graphics...
Creating Province #
Loading Map (Creating Shaders)...
Loading Map (Creating Terrain)...
Loading Map (Creating Borders)...
Loading Map (Creating Straits)...
Loading Map (Creating Textures)...
Loading Map (Creating Trees)...
Loading Map (Creating Rivers)...
Loading Map (Creating objects)...
Initializing Game...

Log files

The game stores various log files in your EU4 user folder: (\\Documents\Paradox Interactive\Europa Universalis IV\logs\). These are overwritten every time the game is started.

To enable full error logging, add the -debug launch command via Set Launch Options in Steam.

File	Description	Usefulness
ai.log	Prints the country selection of the player and then the Starting AI line.	Low
error.log	Prints the various non-fatal errors. Many errors can be ignored, although almost all errors relating to files in the common folder should be fixed.	High
error_old.log	The error.log from the previous game launch.	Low
error_old_old.log	The error.log from the second previous game launch.	Low
exceptions.log	Prints the stacktrace when the game crashes to desktop. Currently only prints the hexadecimal address, making this file fairly useless.	Low
executedcommands.log	Prints the internal commands uses by the player and AI.	Low
game.log	Prints the actions taken by countries in game. Useful when the crash is due to a specific action.	High
graphics.log	Prints the graphical errors relating to positions.	Low
local_temp.log		Low
memory.log	Prints the memory used during setup. Useful for crashes during the loading process, to see when the game crashed.	High
message.log	Prints the session info for the current session.	Low
profiling.log	Prints the profiling output if using the profiling .exe file.	High
random.log		Low
random02.log		Low
receivedcommands.log	Prints the internal commands received by the player in multiplayer.	Low
sentcommands.log	Prints the internal commands sent by the player in multiplayer.	Low
setup.log	Prints the completion of setup loading for each part of the process. Very useful for discovering which file may be causing a crash.	High
setup_error.log	Prints errors in the /Europa Universalis IV/common/countries files. Typically errors are of low importance.	Low
system.log	Prints the system information EU4 is loaded on.	Low
system_interface.log	Prints interface errors.	Low
text.log	Prints asserts on localization keys.	Low
time.log	Prints the time it takes for the various loading steps to complete, and the tick interval. Very useful for crashes during the loading process, to see when the game crashed.	High

Debugging

Generally, when debugging you want to narrow down the possible causes for a crash. This is why it is best to run your mod after every change, so any issues become immediately apparent, and you can find the cause easily since it'll be the last file you edited.

If this is not possible, then you want to isolate the potential causes. This is done by moving the suspected files and folders out of your mod folder and into a temporary folder, and then launching the mod without them. This requires a good amount of knowledge of how each file works together, so you can safely isolate files and folders without introducing broken dependencies.

Typically you can easily isolate the events, decisions, missions and interface folders without too much worry. Then in the common folder, remove files or folders one-by-one, re-launching the game each time to determine which is causing the issue. If none, then it is likely the issue is in the history or map folder. Repeat this process throughout them.

Crashes

Most fatal errors that cause crashes to desktop can be very difficult to debug without extensive knowledge of modding. The following list is of known crashes to help modders debug:

Crash	Fix
During "Loading Databases"	If you are using the defines.lua, check you have included all the entries that vanilla includes. Check that there are no references to non-existing files. A tag in country_tags must not reference a file that does not exist. Make sure that all defined colonial regions have at least one province assigned. Scripted Effect / Meta Script with wrongly coded (leads to stack overflow exception) -> conditional input not used correctly, [] used for something thats not an conditional input e.g. localisation, non closed $input$ like $input
During "Initializing Maplogic"	Check that the gamelogic map images have been saved in the correct formats. Make sure the map files used follows the guidelines listed in Map modding. default.map province limit isn't higher than the last province ID in definition.csv. A province ID in default.map no longer exists in the definition.csv. A province ID in adjacencies.txt no longer exists in the definition.csv. A province ID in area.txt no longer exists in the definition.csv. A province ID in climate.txt no longer exists in the definition.csv. A province ID in continent.txt no longer exists in the definition.csv. A province ID in terrain.txt no longer exists in the definition.csv. A province ID in trade_winds.txt no longer exists in the definition.csv. A province ID in area.txt no longer exists in the definition.csv. terrain.bmp has a missing or corrupted color table. rivers.bmp has a missing or corrupted color table. trees.bmp has a missing or corrupted color table. Map dimensions are not a product of 128. The provinces.bmp exceeds 52 megabytes. The provinces.bmp contains provinces that are too large.
During "Loading History Files..."	Check that the history files do not reference any missing country tags or provinces IDs.
During "Loads Flags..."	Check that the history files do not reference any missing country tags (specifically the diplomacy folder).
During "Loading Graphics..."	Check that the graphical map images have been saved in the correct formats. Make sure the map files used follows the guidelines listed in Map modding.
During "Loading Map (Creating Straits)..."	Check that the adjacencies.txt file lists valid straits.
Clicking Play in the lobby	The issue can lie within the common files: Missing entries in required files such as static_modifiers Missing entries for modifiers used in effects or triggers. History files: A country capital defined in history/countries references a province id that has no pixels in map/provinces.bmp.
Clicking a Province	* Make sure the province belongs to a continent in continent.txt. Make sure the province belongs to an area in area.txt.
Crash when zooming into a specific place	Can be caused by a certain country in the area's graphical_culture = <misspelled>
Nation Designer Government Tab when using more than 3 Government Ranks	The nationadesignerview.gui file needs to be edited to have additional icon_gov_desc_* and gov_desc_* for each new level of government rank.
Crash on Hover in an Interface	Typically caused by a clause missing from the relevant files, i.e. the army professionalism static modifiers when hovering over the Hire General button. It may also be caused by errors in on_actions.txt.
Trying to Move a Capital	Often caused by missing or misnumbered provinces in continent.txt.
Hovering over a country in the Great Powers list	Also often caused by missing or misnumbered provinces in continent.txt.

This process will almost always allow you to discover the cause of a crash, although it is tedious.

Profiling

Since patch 1.23, Europa Universalis IV includes a performance profiler alongside the normal game. This tool is useful for modders that want to measure and diagnose poor performance within their mods.

To use the profiler, you need to launch the game launcher by click eu4_profiling.exe within the game installation folder. This will launch the game launcher, which you can then use to select your mod and launch the game.

Once in game, allow the game to run until you have reached a suitable duration, and then open the console and type dump_script_profiling to write to the profiling.log in the logs folder.

The profiling.log should be viewed in a mono-spaced font for best readability.

Modding

Documentation

Effects • Triggers • Modifiers • Scopes • Variables • Localisation • Customizable localization • Run files

Scripting