Mod troubleshooting
Troubleshooting is the identification of the cause of crashes, bugs or other problems.
Overview[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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.
|
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.
|
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. |
During "Loading Map (Creating Tree)..." | * Check that the trees.bmp file is not corrupted in any manner.
|
Clicking Play in the lobby | The issue can lie within the common files:
History files:
|
Clicking a Province | * Make sure the province belongs to a continent in continent.txt.
|
Crash when zooming into a specific place | Can be caused by a certain country in the area's graphical_culture = <misspelled>.
It may also happen if you did not assign a port to a coastal province and the AI is forced to send out their ships, e.g. after being sieged down. |
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[edit | edit source]
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 with whatever mods you had selected previously in the launcher. In other words, if you wish to test the performance of the game with mods enabled, be sure to enable these mods before launching eu4_profiling.exe.
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.
Documentation | Effects • Triggers • Modifiers • Scopes • Variables • Localisation • Customizable localization • Run files |
Scripting | Scripted function • Advisors • Ages • Bookmarks • Buildings • Casus belli • Colonial regions • Countries • Culture • Decisions • Defines • Diplomatic actions • Disasters • Empire of China • Estates • Events • Factions • Government • Great projects • History • Holy Roman Empire • Idea groups • Institutions • Mercenaries • Missions • Modifiers • Nation designer • On Actions • Parliament • Peace treaties • Policies • Rebel types • Religion • Subject types • Technology • Trade companies • Trade goods • Units |
Map | Map • Nation designer • Random New World • Trade nodes |
Graphics | 3D Models • Interface • Graphical Assets • Fonts • Particles • Shaders • Unit models |
Audio | Music • Sound |
Other | Console commands • Checksum • JoroDox mod making tool • Mod structure • Troubleshooting • The Validator • Run files |
Guides | Adding a province • Save-game editing |