Troubleshooting Mods

Due to the complex nature of some mods, things can sometimes go wrong. This page should be used for troubleshooting issues when installing mods for the game. To help everyone involved, please make sure you have followed all of these troubleshooting steps before contacting a mod developer about the issue. Modders are encouraged to link users to this page if they believe it will help the user solve their problem.

Mods are not showing up in the Mod Manager

This particular issue can occur when restoring a backup from an older on a new system or when switching users. The path to the folder in which the game searches for user-installed mods is absolute, which means that it contains a user name. If this user name changes, as a result the game will ignore any mods you copied over.

You can fix this by manually changing the paths.

1. Close the game.
2. Head over to %AppData%\VintagestoryData (Windows) and
3. open the files clientsettings.json and serverconfig.json with a text and code editor of your choice.
4. In both of those, look up the key "modPaths",
5. change the user name (in this example Brady),
6. save the changes and start the game.

Due to the edits you have made, the mod manager should be populated once again.

Version Checking

When installing a mod, you need to make sure that the version of the mod is made for the version of the game you are playing.

Mods on the ModDB all have a files tab, which lists all the mod versions that are compatible with what game versions. Ensure that you are using the most up-to-date mod version that supports your game's version. The mod will likely not work as intended or at all if you use the wrong version.

As shown in the above screenshot, mod version 3.6.6, although is the latest, does not support game version 1.19.8. Installing a mod version that is for a different game version will likely lead to issues.

Compatible Mods

Although the game has a lot of modding capabilities, not all mods work friendly with each other, and compatibility issues can cause game-breaking issues.

If you have several mods, the chance of mod conflicts becomes more and more likely. These are usually due to two mods trying to interfere with very similar aspects of the game. By disabling mods through the mod manager, you should try to pinpoint what mod(s) is/are not compatible, and then use whichever one is more likely.

Finding out which mod is causing issues...

There exists a simple "divide-and-conquer" method for finding out what mod is causing issues in a game. This method is also known as "binary search".

1. Firstly, find a method to always recreate the issue. This will allow you to test later on.
2. In the main menu, in the mod manager, disable half of your mods.
3. Start a new world, and see if the issue remains.
4. If the issue still happens, then the broken mod must be in the enabled list, so disable half of the enabled mods and repeat the process.
5. If the issue does not still happen, then the broken mod must be in the disabled list. Enable half of the disabled mods, and repeat the process.
6. Keep repeating the process until you have found a single mod that, when enabled, causes the problem, and when disabled, the problem goes away.

You should now know what mod is causing issues with your game. It is your decision on what to do with that mod.

Note
To prevent a corruption of the world you are playing, all tests should be done on a new world or a copy of the world you are experiencing problems in.

Duplicate installs

When more than one copy of the same mod is installed, Vintage Story will attempt to load only the one with the highest version. However, sometimes having a duplicate code mod can cause the following error:

System.Exception: Don't know how to instantiate item of class 'example' did you forget to register a mapping? In place of 'item' it may instead say 'block', 'entity', 'collectible behavior', etc, and in place of 'example' will be the name of something registered by a mod.

To fix this, check all mod folders and make sure that only one copy of each mod is installed.

If all else fails...

If you have gone through the above steps and the mod is still not working as expected, then you can report the issue to the mod developer and they will be able to assist you further.