-
Notifications
You must be signed in to change notification settings - Fork 7
Client Troubleshooting
This is a collection of common problems and solutions for not working modded games. Please see the dedicated server troubleshooting guide for common issues with dedicated servers.
- If your game is crashing before you see the main menu you have the wrong version of BepInEx. (Jump to this issue)
- Make sure BepInEx is installed and is loading. (Jump to this issue)
- Check your log file for errors. If the error contains a mod name that mod is likely related to, or the cause of your issue. Contact the mod author for further help, or seek assistance in one of the modding discords.
BepInEx is the mod loader we use for valheim modding. Without BepInEx none of your mods will work. Avoid using the generic BepInEx download from github and get the Valheim community supported BepInEx pack. For manual installations please read the instructions included on that page (the readme). If using the thunderstore mod managers most mods will install this pack for you automatically.
Steps to check if BepInEx is running:
- Expect a BepInEx popup log window when you launch the game. It is enabled by default with the BepInEx pack.
- Look for a message in the top left of the main menu listing "Plugins Loaded", and a warning about playing modded in the bottom right.
- Check your Bepinex folder for a file called logoutput.log. This file will be re-generated on a successful startup by default.
- If using the Thunderstore mod managers you can get to this file location from profile settings -> browse profile folder
If none of the above 3 are true then it is likely bepinex did not start for you. Here are some additional tips:
To get the start script to work add %command% to the end of your steam launch arguments. The full call for steam deck will look something like: ./start_game_bepinex.sh ; echo %command%
- Check that your profile name has no spaces in it. In some cases this can cause the path discovery to fail, especially for Linux.
- Under profile settings, open the Locations tab. There are several paths here that must be correct for the manager to work.
- Change Steam Directory: This should point to your main steam installation. To change select the appropriate steam.exe file.
- Change Valheim Directory: This should point to your Valheim installation. To change select the appropriate valheim.exe file.
On some game updates the BepInEx pack will break, causing the game to crash before displaying the main menu. Make sure to install the correct version of the BepInEx pack (link provided above) for your game version. If you are playing on the public test branch you will likely run into this issue from time to time. It is not recommended to use mods on the public testing branch as it exists to help the game developers catch vanilla bugs - not for you to play new content early with mods.
Mods can give you the ability to corrupt your world by bypassing vanilla limitations. If your world gets corrupted you can attempt to fix it with this Save Recovery Mod. Be sure to first make extra backups of all save files so they do not get deleted or overwritten while you are debugging the issue. If the save recovery mod does not work you may have to restore a backup to before the issue occurred. If your world continues to get corrupted you will need to remove the mod that is causing it. For more detailed information on potential causes read the description of the save recovery mod.
If a mod calls "UnpatchAll" on game close, it will sometimes shut down other mods too soon. This can cause corrupt or incomplete character and world saves. It can be very difficult to track down a mod that does this, but if you see this warning at the end of your log file you can know this is likely happening to you:
[Warning: HarmonyX] UnpatchAll has been called - This will remove ALL HARMONY PATCHES.
Common character save issues can appear when using the Server Characters mod, especially if another mod calls "UnpatchAll". Server Characters requires extra time at shutdown to send the save data to the server. If seeing issues using this mod avoid using the "Quit" button when connected to the server (in-game), and use "Logout" to return to the main menu before quitting. If the problem is indeed another mod calling "UnpatchAll" then removing the offending mod should fix this specific issue.
If you do not have a mod calling "UnpatchAll" another thing you can try to fix save issues is to disable Steam Cloud Saves. This is a toggle in your steam setting for Valheim under the General tab.
If your game is starting modded, but you are experiencing bugs and other issues, the best tool you will have for troubleshooting is the log file (explained above how to find it). There are many modding communities that exist that can help you understand this log file. If this guide does not help you it is recommended to seek out a modding discord for human assistance.
Here are some more general debugging tips:
Unofficial re-uploads of mods can sometimes stagnate and will not receive updates. To check if your mod is still supported you must find the original source of the mod. This is commonly an issue with Nexus-only mods being posted to Thunderstore without the author's permission. If you see a mod have multiple versions by multiple authors it is likely a re-upload.
Valheim updates break mods a lot. The older a mod is the less likely it will be working. Check the dates on your mods to get a general sense of what is old vs new. For example, there are very few working mods last updated in 2021, though there are always exceptions. Remember, a game update is not always guaranteed to break existing mods.
There was a community discord bot created to help find old mods from your log file. You will find the bot is activated in a lot of general modding discords, or you can private message this bot directly. The bot can also parse your log file for errors and makes it easier to find and understand your mod issues.
Another option, especially if you do not use discord, is to use this Mod Age mod and get the information in-game.
Larger Mod Breaking updates:
- 0.211.7 Crossplay: September 28th, 2022
- 0.212.7 Mistlands: December 6th, 2022
- 0.217.4 Hildir: August 22nd, 2023
- 0.217.22 Hildir Patch: October 5th, 2023
Sometimes you will see error logs in your log file that contain a mod name. If you can identify which mod is throwing an error it is best to seek help from that mod author. For example, this is an error from using an old version of a mod called MultiCraft. You can see the mod name listed several times in the error stack trace:
[Error : Unity Log] ArgumentException: Undefined target method for patch method static void MultiCraft.CraftGUI_Patch::Postfix(Container container)
Stack trace:
HarmonyLib.PatchClassProcessor.PatchWithAttributes (System.Reflection.MethodBase& lastOriginal) (at <...>:0)
HarmonyLib.PatchClassProcessor.Patch () (at <...>:0)
Rethrow as HarmonyException: Patching exception in method null
HarmonyLib.PatchClassProcessor.ReportException (System.Exception exception, System.Reflection.MethodBase original) (at <...>:0)
HarmonyLib.PatchClassProcessor.Patch () (at <...>:0)
HarmonyLib.Harmony.<PatchAll>b__11_0 (System.Type type) (at <...>:0)
HarmonyLib.CollectionExtensions.Do[T] (System.Collections.Generic.IEnumerable`1[T] sequence, System.Action`1[T] action) (at <...>:0)
HarmonyLib.Harmony.PatchAll (System.Reflection.Assembly assembly) (at <...>:0)
HarmonyLib.Harmony.CreateAndPatchAll (System.Reflection.Assembly assembly, System.String harmonyInstanceId) (at <...>:0)
MultiCraft.MultiCraftPlugin.Awake () (at <525c03844ebf4e3aacaa0ef0188eddce>:0)
UnityEngine.GameObject:AddComponent(Type)
BepInEx.Bootstrap.Chainloader:Start()
UnityEngine.UI.Graphic:get_canvas()
TMPro.TextMeshProUGUI:OnCanvasHierarchyChanged()
Other times it will be impossible to know which mod is causing an error since the stack trace will not contain a specific mod name. For example:
[Error : Unity Log] NullReferenceException: Object reference not set to an instance of an object
Stack trace:
(wrapper dynamic-method) FejdStartup.DMD<FejdStartup::OnWorldStart>(FejdStartup)
UnityEngine.Events.InvokableCall.Invoke () (at <...>:0)
UnityEngine.Events.UnityEvent.Invoke () (at <...>:0)
UnityEngine.UI.Button.Press () (at <...>:0)
UnityEngine.UI.Button.OnPointerClick (UnityEngine.EventSystems.PointerEventData eventData) (at <...>:0)
UnityEngine.EventSystems.ExecuteEvents.Execute (UnityEngine.EventSystems.IPointerClickHandler handler, UnityEngine.EventSystems.BaseEventData eventData) (at <...>:0)
UnityEngine.EventSystems.ExecuteEvents.Execute[T] (UnityEngine.GameObject target, UnityEngine.EventSystems.BaseEventData eventData, UnityEngine.EventSystems.ExecuteEvents+EventFunction`1[T1] functor) (at <...>:0)
UnityEngine.EventSystems.EventSystem:Update()
This is a very common issue reported. Typically you can notice when this starts to happen since your game will lag and framerate will drop dramatically, and this error will get spammed in your log file. You can fix it temporarily by logging out and back in. Many different mods can cause it, old and new. Narrowing down the offending mod may be difficult.
More specifically: This error happens due to an invalid object being removed from the scene when you move through the world and unload an area. You may not notice what object (creature, piece, item, etc) is the root cause, but pay attention to when it starts and what biome the general area you just left was. This can help you identify the offending object, or narrow down possible causes. If you can figure out what causes the issue you should report the problem to the mod author so they can fix it. Otherwise, removing the offending mod will make this error go away. To sometimes help find the issue, you can install this mod AzuDevMod. It will print to the console which prefab and mod caused the issue if it has enough information, otherwise it will print what it can.
[Error : Unity Log] NullReferenceException: Object reference not set to an instance of an object
Stack trace:
ZNetScene.RemoveObjects ...
This issue is related to mod age and game updates breaking mods. Removing the old mod will make these errors go away. These lines will typically occur right after a plugin is loaded on startup, which can make it easier to identify which mod is causing it.
Example:
[Warning: HarmonyX] AccessTools.DeclaredMethod: Could not find method for type InventoryGui and name Show and parameters (Container)
[Error : Unity Log] ArgumentException: Undefined target method ...
This issue is related to mod age and game updates breaking mods. Removing the old mod will make these errors go away. It is often harder to identify which mod is causing these errors.
Example:
[Error : Unity Log] MissingFieldException: Field 'PlayerProfile/PlayerStats.m_deaths' not found.
This is caused by a mod that has not been updated since the 0.216.9 game patch on June 12th, 2023.
[Error : Unity Log] MissingFieldException: Field 'Terminal.m_input' not found.
This specific MissingFieldException was commonly seen after the Hildir update 0.217.14 on August 22nd, 2023. All mods using console commands needed an update in order to work again.
[Error : Unity Log] TypeLoadException: Failure has occurred while loading a type.
Stack trace:
(wrapper dynamic-method) Terminal.DMD<Terminal::InputText>(Terminal)
Terminal.SendInput () (at <078f0bc822994e19924df877ab09132f>:0)
The above is very commonly caused by Aedenthorn mods and reuploads on Thunderstore after the 0.217.46 game patch. Use caution with these mods as they are not well maintained (Example: CraftFromContainers, Clock, Compass, etc).
There is a mod called TerminalChecker that can detect which mods patch the terminal. Install this and launch the game, the mod will print debugging lines to the log file for every mod that could potentially be the problem (you can search the file for TerminalChecker). It will print broken mods and working ones alike, not all mods printed will be broken. It is just a detector mod, and it is not 100% accurate, it will help guide you in fixing the issue a bit faster than without aid.
This specific MissingFieldException was commonly seen after the Hildir update, caused by mods using a common modding package called ServerSync. Any mods using ServerSync needed to be updated after this game patch to work again. This Server Sync Fix mod can attempt to fix the issue, or at least identify which mods may have an outdated version of this package in the log file. This mod is not 100% accurate, it can still mis-identify mods that have a custom version of the ServerSync package. Check the last mod update date if unsure.
This method was removed with the Ashlands update version 0.218.15 on May 14th, 2024. This would be caused by a mod that has not been updated since that date. One known mod to cause this is ValheimLegends version 0.5.0.