BepInEx Setup

Valheim: Mastering the BepInEx Modding Framework

In the world of Valheim modding, BepInEx is the foundation upon which almost every mod is built. It is a "Unity Injector" that allows external code (DLLs) to modify the way the game behaves. Without BepInEx, massive quality-of-life mods like *Valheim Plus* or *Epic Loot* simply cannot function.

Manual Installation & Directory Structure

If you are not using the Supercraft 1-Click Installer, you must ensure the following structure in your root folder:

• /BepInEx/: the framework, with core, plugins, patchers and config inside.
• doorstop_config.ini: the configuration that tells Valheim to load BepInEx when it starts.
• winhttp.dll on Windows: the file that starts the injection.
• On Linux, doorstop_libs/ and the start_server_bepinex.sh script, which launches the server with BepInEx loaded; the pack ships both.

Configuring "Doorstop"

If BepInEx isn't loading, check your doorstop_config.ini. The current pack uses Doorstop 4, where the [General] section must have enabled = true and point at the preloader. Guides written for Doorstop 3 show an [UnityDoorstop] section with targetAssembly; that format is older.

[General]
enabled = true
target_assembly=BepInEx\core\BepInEx.Preloader.dll

Advanced Troubleshooting: The Dependency Loop

Many mods require Jotunn or HookGenPatcher to work.

Comprehensive Troubleshooting Guide

BepInEx Not Loading

• Symptom: Server starts but mods don't work. No BepInEx console output.
• Check Doorstop Config: Verify doorstop_config.ini has enabled=true.
• Verify Installation: Ensure BepInEx folder structure is correct with all core files.
• Check Permissions: Verify the server can read doorstop_config.ini and the BepInEx folder, and on Linux that start_server_bepinex.sh is executable.
• Log Files: Check if LogOutput.log is being generated. If not, BepInEx isn't loading at all.

Mods Not Appearing in Game

• Wrong Folder: Ensure DLLs are in /BepInEx/plugins/, not root or subdirectories.
• Missing Dependencies: Many mods require Jotunn, HookGenPatcher, or MMHOOK. Install required dependencies.
• Version Mismatch: Ensure BepInEx version is compatible with Valheim version.
• Load Order Issues: BepInEx orders plugins by the dependencies they declare, so renaming DLLs does not change the order. Install the dependency the mod asks for instead.
• Config Conflicts: Duplicate config files or corrupted configs can prevent loading.
• Check Logs: LogOutput.log will show which mods failed and why.

Server Crashes on Startup

• Incompatible Mod: One of your mods is incompatible with current Valheim version.
• Corrupted Download: Re-download BepInEx and all mods from official sources.
• Dependency Loop: Mod A requires Mod B, Mod B requires Mod C, but Mod C is missing.
• Memory Issues: Too many mods can exceed available RAM. Disable non-essential mods.
• Duplicate Mods: Having multiple versions of the same mod causes crashes.
• Troubleshoot: Disable all mods, enable one-by-one until crash occurs.

Specific Mod Errors in Logs

"Assembly load failed" or "TypeLoadException"

• Corrupted DLL: Re-download the affected mod.
• Wrong BepInEx: Valheim needs the Mono build of BepInEx 5 (BepInExPack Valheim), not BepInEx 6 or an IL2CPP build.
• Missing Framework: Some mods require specific .NET Framework versions.

"Missing dependency"

• Identify Missing Dependency: Check the mod's Thunderstore page for requirements.
• Common Dependencies: Jotunn, HookGenPatcher, MMHOOK_Valheim.
• Install Location: Dependencies go in /BepInEx/plugins/ or /BepInEx/patchers/ as specified.

"Version mismatch"

• BepInEx Version: Update BepInEx to latest version.
• Game Version: Ensure Valheim is updated. Old mods may not work with new versions.
• Dependency Version: Update all dependency mods to match mod requirements.

Client-Side Issues

Players Can't Join Modded Server

• Version Mismatch: Players need exact same mod versions as server.
• Missing Mods: All players must have all server-side mods installed.
• Config Differences: Some mods (like Valheim Plus) require matching configs.
• Profile Codes: Use r2modman profile codes to sync exact mod lists.
• Enable Mods: Ensure players are launching with "Start Modded" button.

Game Won't Launch with Mods

• Incompatible Mod: One mod conflicts with others or game version.
• Corrupted Install: Delete BepInEx folder and reinstall completely.
• Antivirus: Some antivirus software blocks mod DLLs. Add exceptions.
• Launch Arguments: Verify game has proper launch parameters.
• Mod Manager Issues: Try launching without r2modman to isolate the issue.

Performance Issues

Server Lag with Mods

• Too Many Mods: Each mod adds overhead. Disable unused mods.
• Resource-Intensive Mods: Some mods like Epic Loot generate many items. Configure properly.
• Autosave Frequency: Some mods increase save frequency. Adjust intervals.
• Player Sync: Mods that sync data between players increase network load.
• Monitor Resources: Check CPU/RAM usage in server control panel.

Client Framerate Drops

• Visual Mods: HD textures and visual effects mods impact performance.
• UI Mods: Complex interface overlays can cause FPS drops.
• Item Density: Mods that add many items increase memory usage.
• Disable Effects: Reduce particle effects in mod configurations.
• Hardware Limitations: Ensure your PC meets modded game requirements.

Configuration Issues

Settings Not Applying

• Wrong Config File: Ensure you're editing the correct .cfg file.
• Server vs Client: Some settings must be on server, others on client.
• Format Errors: Incorrect config format prevents settings from loading.
• Restart Required: Most config changes need server restart.
• Default Override: Some configs reset to default on updates.

Config File Not Generated

• Not Started Yet: Config files generate on first successful mod load.
• Mod Failed to Load: If mod doesn't load, config won't generate.
• Manual Creation: Manually create config using examples from mod documentation.
• Permissions: Ensure server has write permissions to config directory.

Common Dependency Issues

Jotunn (Jötunnheim)

• Purpose: Required for almost all complex UI and item mods.
• Installation: Place Jotunn.dll in /BepInEx/plugins/.
• Version: Must match Jotunn version required by each dependent mod.
• Common Error: "Jotunn not found" when using Jotunn-dependent mods.

HookGenPatcher

• Purpose: Required for mods that change core game mechanics.
• Installation: Place in /BepInEx/patchers/, NOT plugins folder.
• Common Mistake: Putting HookGenPatcher in plugins instead of patchers.

MMHOOK_Valheim

• Purpose: Required for older mods that need manual method hooks.
• Installation: Place MMHOOK_Valheim.dll in /BepInEx/plugins/.
• Version Critical: Must match specific Valheim version requirements.

Best Practices for Stable Modded Servers

Installation Guidelines

• Source Reliability: Only download from Thunderstore or official sources.
• Version Tracking: Keep notes of which mod versions work together.
• Incremental Testing: Add one mod at a time, test thoroughly.
• Backup Often: Always backup before adding new mods.
• Read Documentation: Check each mod's installation instructions and requirements.

Maintenance

• Regular Updates: Keep mods updated for new Valheim versions.
• Clean Install: Occasionally reinstall BepInEx and mods completely.
• Monitor Logs: Check LogOutput.log regularly for warnings.
• Performance Monitoring: Track server performance metrics over time.
• Community Feedback: Stay updated on known issues and solutions.

Shield your server with peak performance. Set up a Valheim server with Supercraft and take advantage of our internal pre-configured BepInEx environment for instant modding.