mini-server-manager/managed-valheim
1
1 Fork 0
Code Issues 5 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity
Page: Troubleshooting
Pages
Backup & Restore FAQ Home Installation Modding Guide Quick Start Troubleshooting Version History
Clone
1
Troubleshooting
the_minisip edited this page 2026-10-16 13:24:51 -03:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Troubleshooting

This page provides solutions to common issues encountered when running the Managed Valheim server. It covers startup problems, update failures, mod issues, backup errors, and connectivity problems.

1. Server Will Not Start

Check Container Logs

Open the TrueNAS SCALE app logs and look for errors related to:

  • SteamCMD installation
  • BepInEx extraction
  • File permissions
  • Missing environment variables

Common Causes

  • Incorrect world name
    Ensure WORLD_NAME matches the actual world directory name.
  • Missing password
    Valheim requires a password unless PUBLIC=0.
  • Corrupted world files
    Restore from a container backup or Valheim’s internal rolling backups.

2. SteamCMD Update Failures

SteamCMD installs Valheim into /opt/valheim_base. If updates fail:

  • Verify the steam user owns the directory.
  • Check for network issues blocking Steam.
  • Restart the TrueNAS SCALE app to retry the update.

The container automatically retries updates on each startup.

3. BepInEx Not Loading

If BepInEx does not initialize:

  • Check for errors in:
    /opt/valheim/BepInEx/LogOutput.log
  • Ensure the BepInEx ZIP downloaded correctly.
  • Verify the managed wrapper script exists:
    /opt/valheim/start_server_managed.sh
  • Restart the container to force reinstallation.

4. Mods Not Working

Mods must be installed in: 

/opt/valheim/BepInEx/plugins

Checklist

  • DLL files are in the correct directory.
  • No mods were placed in /opt/valheim_base.
  • Mod versions match the current Valheim version.
  • Check BepInEx logs for load errors.

Server Crashes After Adding a Mod

  • Remove the most recent mod.
  • Check for missing dependencies.
  • Review mod documentation for compatibility issues.

5. World Not Saving

If the world is not saving correctly:

  • Verify the world directory exists:
    /root/.config/unity3d/IronGate/Valheim/worlds_local/<WORLD_NAME>
  • Check file permissions.
  • Ensure the dataset is mounted correctly in TrueNAS SCALE.

6. Backup Issues

No Backups Are Being Created

  • Verify the /backups volume is mounted.
  • Check container logs for backup messages.
  • Ensure BACKUP_INTERVAL is set correctly.

Backups Are Not Being Pruned

  • Verify BACKUP_RETENTION_DAYS is set.
  • Ensure backup filenames follow the expected format.
  • Check permissions on the backup directory.

Understanding Valheim’s Internal Rolling Backups

Valheim automatically maintains up to 5 rotating backups: 

<WORLD_NAME>.db
<WORLD_NAME>.fwl
<WORLD_NAME>_1.db
<WORLD_NAME>_2.db
<WORLD_NAME>_3.db
<WORLD_NAME>_4.db
<WORLD_NAME>_5.db

These are separate from container backups and can be used for quick restores.

7. Connectivity Problems

Players Cannot Join

  • Verify ports 2456–2458 UDP are exposed.
  • Ensure your firewall allows inbound UDP traffic.
  • Check that SERVER_PASSWORD is correct.
  • Ensure the server is set to public (PUBLIC=1).

Server Not Appearing in Browser

  • Direct connect using IP and port.
  • Public listing may take several minutes to propagate.
  • Check NAT or port forwarding rules.

8. Performance Issues

  • Reduce mod count.
  • Check for heavy mods causing CPU spikes.
  • Ensure your TrueNAS SCALE node has sufficient RAM.
  • Review BepInEx logs for plugin errors.

9. File Permission Errors

The steam user must own:

  • /opt/valheim_base
  • /opt/valheim
  • /opt/steamcmd

If permissions break, restart the app — the entrypoint resets ownership.

10. When All Else Fails

  • Restart the TrueNAS SCALE app.
  • Restore from a backup.
  • Temporarily remove mods.
  • Check logs for BepInEx or SteamCMD errors.

Next Steps

This troubleshooting guide covers the most common issues. If problems persist, review logs carefully or restore from a known-good backup.