From Hearts of Iron 4 Wiki
Jump to navigation Jump to search

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


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 errors occur when the game encountered invalid data or broken syntax. These errors are almost always printed to the error.log.


Performing testing is vital to debugging a mod. Typically this is done via the in-game console with commands.

These are useful console commands for modders:

Command Usage
reloadfx all Reloads most of the effects used in the game, such as fog of war, the HDR and opacity of country borders, ect.
reload texture Reloads most of the textures used in the game, such as leader portraits, technology icons, etc.
reload localization Reloads most of the localization used in-game, such as event titles and descriptions.
reload defines Reloads the defines files from /Hearts of Iron IV/common/defines/.
reload focus Reloads the focus trees in /Hearts of Iron IV/common/national_focuses/.
reloadoob Reloads the starting OOB file for the specified tag.
reloadtechnologies Reloads the technology files. Will cause a crash if an error is encountered.
reloadinterface Reloads the interface files (.gui).
reload decision Reloads the decision files (.gui and common/decisions).
tdebug Activates the debug tooltips, displaying important information such as state ID, province ID, etc.
event Fires the specified event immediate for the current player country.
nocb Removes restrictions on diplomatic actions.
observe Places the player into the observer slot, allowing the game to pass without player input.
aiview Displays the AI priorities when hovering over specific buttons, such as technology.
tag Switches the player to another country.
update_loc Reloads the specified localization key.
updateequipments Reloads the equipment files in /Hearts of Iron IV/common/units/equipment/.
updatesubunits Reloads the unit files in /Hearts of Iron IV/common/units/.
research_on_icon_click Activates research on click, allowing you to click on technologies to research them instantly.
Focus.NoChecks Removes the trigger checks for focuses.
Focus.AutoComplete Activates instant completion for focuses.
set_country_flag Sets the specified country flag for the current country.
add_ideas Adds the specified idea to the current country.

Log files[edit]

The game stores various log files in your HOI4 user folder: (Windows: \\Documents\Paradox Interactive\Hearts of Iron IV\logs\, Linux: .local/share/Paradox Interactive/Hearts of Iron 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 AI choices undertaken. Medium
ai_trace.log Prints the AI movements undertaken (divisions, ships, air, etc.) 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
exceptions.log Prints the stack trace when the game crashes to desktop. Low
executedcommands.log Prints the internal commands uses by the player and AI. Low
game.log Prints the actions that were 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, rivers, and trees. 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
postedcommands.log Low
random.log Prints times for game state changes. 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
system.log Prints the system information HOI4 is loaded on. Low
system_debug.log Prints interface errors. Medium
text.log Prints asserts on localization keys. Medium
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. Medium

Crash data log[edit]

When the game crashes, it provides information on system settings and what caused it to crash in Documents/Paradox Interactive/Hearts of Iron IV/crashes. Although most of the time this is not beneficial as to what caused it to crash, the error log could contain clues.
Adding the -crash-data_log launch command via Launch Options in Steam, will also cause the meta.yml file in that folder to contain the last read line of code before crashing. This can be helpful to find the file. Although, if the last read line of the file given is the last line in the file, it's rather likely the game crashed on the next read file instead, which is quite difficult to locate.

Additional details[edit]

A version tracking website, such as [Gitlab] or [Github], can be used to keep track of updates to the code. As such, it can be beneficial to use them and regularly push mod's updates to them in order to limit the selection of possibly problematic files.

In case the game crashes on startup, but there's no obvious reason why in the error log and it's unknown what was last changed since the last time, the mod could have folders strategically removed. As an example, it is almost always possible to remove the entire /Hearts of Iron IV/common/ folder from the mod without the game crashing, provided debug mode is turned on.

Logged errors[edit]

These errors in the error log are not necessarily clear-cut to understand, so this goes into more details into them. This assumes you have debug on. User directory refers to Documents/Paradox Interactive/Hearts of Iron IV in Windows, but the location is different on other systems. Ctrl+Shift+F in most text editors will search in multiple files at the same time, if the game does not specify the location of the error.


  • Unexpected token - The specified point of code does exist but is located in an unexpected location. Common causes for this occurring are invalid syntax, often caused by unnecessary or missing closing brackets, and typos. Make sure the spelling is correct and everything is where it's intended to be (Say, in the focus tree, completion_reward = {} is located directly inside of focus = {}. Text editors in the guidelines section of the modding article provide bracket highlighting, which is really useful for checking brackets. Encoding may also sometimes be the cause: UTF-8-BOM encoding completely breaks certain files, such as /Hearts of Iron IV/common/countries/colors.txt.
  • Malformed token - The specified point of code does not exist and thus is completely unexpected. It is possible that the definition for that is missing, such as when adding a trait or an opinion modifier that does not exist, but it can also be a typo. Encoding may also sometimes be the cause: UTF-8-BOM encoding completely breaks certain files, such as /Hearts of Iron IV/common/countries/colors.txt. In case of events, the ID may be invalid because the add_namespace line is missing.
  • Invalid trigger/effect/modifier - It's possible that there was a typo in the name. Double-check syntax if it's not meant to be a trigger/effect/modifier. The error may also be caused by outdated definitions of scripted triggers, scripted effects, or Modifier tokens accordingly.
  • Unknown trigger/effect-type - This is similar to the previous focus, but it happens if instead of a direct argument, the supposed 'trigger' or 'effect' instead has {}. Check brackets and for typos.


  • invalid focus for ai strategy - An invalid national focus is put into /Hearts of Iron IV/common/ai_strategy_plans/*.txt. Emptying out the problematic file or replacing the path for all files at once there will fix the issue.
  • TAG is not in the tag list - A country that is not defined in /Hearts of Iron IV/common/country_tags is used in /Hearts of Iron IV/common/difficulty_settings or /Hearts of Iron IV/history/countries


  • TAG is missing a history file - The tag is defined in /Hearts of Iron IV/common/country_tags but is lacking an entry in /Hearts of Iron IV/history/countries
  • Definition for state id is either missing or invalid - States in /Hearts of Iron IV/history/states cannot go out of order. If there are any gaps between 1 and the last ID, this shows up.
  • State ID conflict - 2 states have the same ID. Do not change filenames in history/states unless there's a replace_path to there. If the base game's state file and the mod's state file have the same name, the mod's will get prioritised, otherwise, both will get loaded.
  • Country does not have any equipment variant for type - With Man the Guns on, each ship defined in /Hearts of Iron IV/history/units needs an equipment variant defined in /Hearts of Iron IV/history/countries via the create_equipment_variant effect.


  • Missing portrait texture in group - A portrait specified in /Hearts of Iron IV/portraits/*.txt does not actually actually exist. The base game has this issue in /Hearts of Iron IV/dlc/dlc021_anniversary_pack/ Keep in mind that dlc folder does nothing in mods and the file has to be in /Hearts of Iron IV/portraits/*.txt for the mod to put it in the game.
  • leader without portrait - A generic leader lacks a definition in /Hearts of Iron IV/portraits/*.txt. Each new ideology requires an entry there for generic political leaders, this article contains documentation.
  • Error loading country flag overlay - Unexpected texture dimensions - The specified flag does not have the correct proportions. Make sure they abide by the dimensions given in the Country creation article.
  • Error loading country flag overlay - Unsupported format - When exporting, the flag was given the wrong formatting. If a file converter is used, this may appear. GIMP, Photoshop, and are suitable replacements. In, this all appears while saving. In Photoshop and GIMP, you may also have to change Image -> Mode to RGB Color. Also in GIMP, you may have to change the image to 32 bits by right-clicking the image layer and choosing 'Add Alpha Channel'.
  • Error loading flag - Warning slow to read format - The image was saved in 24 bits instead of 32. If using or Photoshop, this can be changed in export settings. In GIMP, right-click the layer and then choose 'Add Alpha Channel' before re-exporting.


  • Undefined GUI_TYPE - This GUI element is assumed to exist by the game, but it is missing a definition. This happens with outdated /Hearts of Iron IV/interface/*.gui files. If this error happens, port over the specified element to the file from the base game.


  • Expected quotation mark - There may be an unnecessary space or a special character in the middle of the localisation key. Double-check for that in the specified line and column.
  • Localization file should be in in utf-8-bom encoding - The file is encoded in UTF-8 instead of UTF-8-BOM. Most text editors have the encoding selection in the top bar, but it depends from one to another.


  • Some errors are present in the map definition and have been logged to error.log - Turn on debug mode via launch options
  • Map building is not within specified state. BUILDING IGNORED! - The models of buildings corresponding to states are not located in the states. In order to fix that, in nudge, go to buildings. In there, choose the 'Validate all states' option. Afterward, move the files from the user directory, inside the map folder, to the mod folder.
  • map/buildings.txt is empty - The nudge cannot generate a completely new buildings.txt. Port over first few lines of the base game's buildings.txt and only then use the nudge's generator.
  • Map invalid X crossing. Four provinces share a common corner in the specified coordinates. Sometimes the coordinates are located at the world's edge, in which case it must be kept in mind that the map loops horizontally.
  • Province X has TOO LARGE BOX - A province has a large size of over 1/8th of the map's width or height. Multiple provinces may have the same colour.
  • Province X has only N pixels - The province is really small and can't be easily picked by the player. Consider artificially increasing its size.
  • warning X4008: floating point division by zero - Provinces.bmp is in 32 bits instead of 24 bits.
  • Province has added another strategic region as theirs. - The same province is in several strategic regions. Likely caused by the nudge: manually modify the strategic region in /Hearts of Iron IV/map/strategicregions
  • Naval strategic region is fractioned! - All provinces in naval strategic regions must border each other. If the strategic region has any sea provinces, it automatically becomes a naval strategic region.
  • State has provinces belonging to different strategic areas - All states must be fully contained within the same strategic region. Otherwise, this error appears. Modify the strategic regions manually or via nudge to fix this.

Common unlogged errors[edit]

These errors do not appear in the error log, nonetheless, they can be often committed while modding and their cause isn't always obvious.


  • The mod doesn't work once uploaded on Steam - The launcher does not like when 2 installed mods have the same name. Renaming either one of them via the descriptor.mod file will fix this issue.
  • A file appears to have no effect - Double-check the filepath to the folder for any typos. If the file is a localisation file, check the file name according to Localisation. If you haven't restarted the game, newly-created files will not load-in with debug mode, only edits in existing files. Turn off all other mods (If that's the issue, make sure the mod has dependencies defined). Check that the file is not in the dlc folder: that does nothing in mods, the file has to be in the mod itself.


  • News event only appears for one country - If the event contains fire_only_once = yes, it will fire only once per game, not per country. Removing that line of code will fix the issue, as long as the event does contain major = yes.


  • The country starts with no units - Make sure that you have loaded the order of battle located in /Hearts of Iron IV/history/units via the line that says oob = "TAG_1936" in /Hearts of Iron IV/history/countries, which can be seen in the beginning of each file in the base game's files in that folder.
  • Every single core state starts with resistance - The /Hearts of Iron IV/common/scripted_triggers/00_resistance_initiate_triggers.txt file has been overwritten by the mod. Port it over to the mod.


  • A focus icon shows up as the default icon - Make sure that the focus has the same icon = GFX_<sprite name> as the one you have defined in /Hearts of Iron IV/interface/*.gfx If it's correct, check if it appears in the description or not. If it does, the error is in the shine. A common cause for that is the lack of _shine at the end of the shine's name.
  • A country's flag appears upside down - If the origin point is set to top left instead of bottom left, the game will make it render upside down. Certain file converters, such as XnConvert, do that error. As long as the rest of the rules are followed (No encoding, 32 bits, RGB mode), the default options in GIMP, Photoshop, and will export the flag in the correct orientation.


  • Localisation says something else that I don't want - This can be sometimes seen with such examples as PRC with the Maoism ideology having the name 'Maoism'. This is caused by base game localisation taking priority over the mod's. The Modding article provides information useful in order to locate that file.


  • Some errors are present in the map definition and have been logged to error.log - Turn on debug mode via launch options
  • The nudge files remain in base game - The nudge puts files in Documents/Paradox Interactive/Hearts of Iron IV directly, as it does not know which mods you have open. Put the files inside of the mod folder you've created them for or delete them.