diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..aca84a2
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,236 @@
+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.
+