Add Troubleshooting
the_minisip committed
1 parent
3663ca2735
commit
0eab0d5bcd
1 file changed
+236
+236
@@ -0,0 +1,236 @@
|
||||
<h1><strong>Troubleshooting</strong></h1>
|
||||
|
||||
<p>
|
||||
This page provides solutions to common issues encountered when running the
|
||||
<strong>Managed Valheim</strong> server. It covers startup problems, update
|
||||
failures, mod issues, backup errors, and connectivity problems.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>1. Server Will Not Start</strong></h2>
|
||||
|
||||
<h3><strong>Check Container Logs</strong></h3>
|
||||
<p>
|
||||
Open the TrueNAS SCALE app logs and look for errors related to:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>SteamCMD installation</li>
|
||||
<li>BepInEx extraction</li>
|
||||
<li>File permissions</li>
|
||||
<li>Missing environment variables</li>
|
||||
</ul>
|
||||
|
||||
<h3><strong>Common Causes</strong></h3>
|
||||
|
||||
<ul>
|
||||
<li><strong>Incorrect world name</strong><br>
|
||||
Ensure <code>WORLD_NAME</code> matches the actual world directory name.
|
||||
</li>
|
||||
|
||||
<li><strong>Missing password</strong><br>
|
||||
Valheim requires a password unless <code>PUBLIC=0</code>.
|
||||
</li>
|
||||
|
||||
<li><strong>Corrupted world files</strong><br>
|
||||
Restore from a container backup or Valheim’s internal rolling backups.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>2. SteamCMD Update Failures</strong></h2>
|
||||
|
||||
<p>
|
||||
SteamCMD installs Valheim into <code>/opt/valheim_base</code>. If updates fail:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>Verify the <code>steam</code> user owns the directory.</li>
|
||||
<li>Check for network issues blocking Steam.</li>
|
||||
<li>Restart the TrueNAS SCALE app to retry the update.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
The container automatically retries updates on each startup.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>3. BepInEx Not Loading</strong></h2>
|
||||
|
||||
<p>
|
||||
If BepInEx does not initialize:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>Check for errors in:<br>
|
||||
<code>/opt/valheim/BepInEx/LogOutput.log</code>
|
||||
</li>
|
||||
<li>Ensure the BepInEx ZIP downloaded correctly.</li>
|
||||
<li>Verify the managed wrapper script exists:<br>
|
||||
<code>/opt/valheim/start_server_managed.sh</code>
|
||||
</li>
|
||||
<li>Restart the container to force reinstallation.</li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>4. Mods Not Working</strong></h2>
|
||||
|
||||
<p>
|
||||
Mods must be installed in:
|
||||
</p>
|
||||
|
||||
<pre><code>/opt/valheim/BepInEx/plugins</code></pre>
|
||||
|
||||
<h3><strong>Checklist</strong></h3>
|
||||
|
||||
<ul>
|
||||
<li>DLL files are in the correct directory.</li>
|
||||
<li>No mods were placed in <code>/opt/valheim_base</code>.</li>
|
||||
<li>Mod versions match the current Valheim version.</li>
|
||||
<li>Check BepInEx logs for load errors.</li>
|
||||
</ul>
|
||||
|
||||
<h3><strong>Server Crashes After Adding a Mod</strong></h3>
|
||||
|
||||
<ul>
|
||||
<li>Remove the most recent mod.</li>
|
||||
<li>Check for missing dependencies.</li>
|
||||
<li>Review mod documentation for compatibility issues.</li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>5. World Not Saving</strong></h2>
|
||||
|
||||
<p>
|
||||
If the world is not saving correctly:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>Verify the world directory exists:<br>
|
||||
<code>/root/.config/unity3d/IronGate/Valheim/worlds_local/<WORLD_NAME></code>
|
||||
</li>
|
||||
<li>Check file permissions.</li>
|
||||
<li>Ensure the dataset is mounted correctly in TrueNAS SCALE.</li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>6. Backup Issues</strong></h2>
|
||||
|
||||
<h3><strong>No Backups Are Being Created</strong></h3>
|
||||
|
||||
<ul>
|
||||
<li>Verify the <code>/backups</code> volume is mounted.</li>
|
||||
<li>Check container logs for backup messages.</li>
|
||||
<li>Ensure <code>BACKUP_INTERVAL</code> is set correctly.</li>
|
||||
</ul>
|
||||
|
||||
<h3><strong>Backups Are Not Being Pruned</strong></h3>
|
||||
|
||||
<ul>
|
||||
<li>Verify <code>BACKUP_RETENTION_DAYS</code> is set.</li>
|
||||
<li>Ensure backup filenames follow the expected format.</li>
|
||||
<li>Check permissions on the backup directory.</li>
|
||||
</ul>
|
||||
|
||||
<h3><strong>Understanding Valheim’s Internal Rolling Backups</strong></h3>
|
||||
|
||||
<p>
|
||||
Valheim automatically maintains up to 5 rotating backups:
|
||||
</p>
|
||||
|
||||
<pre><code><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
|
||||
</code></pre>
|
||||
|
||||
<p>
|
||||
These are separate from container backups and can be used for quick restores.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>7. Connectivity Problems</strong></h2>
|
||||
|
||||
<h3><strong>Players Cannot Join</strong></h3>
|
||||
|
||||
<ul>
|
||||
<li>Verify ports 2456–2458 UDP are exposed.</li>
|
||||
<li>Ensure your firewall allows inbound UDP traffic.</li>
|
||||
<li>Check that <code>SERVER_PASSWORD</code> is correct.</li>
|
||||
<li>Ensure the server is set to public (<code>PUBLIC=1</code>).</li>
|
||||
</ul>
|
||||
|
||||
<h3><strong>Server Not Appearing in Browser</strong></h3>
|
||||
|
||||
<ul>
|
||||
<li>Direct connect using IP and port.</li>
|
||||
<li>Public listing may take several minutes to propagate.</li>
|
||||
<li>Check NAT or port forwarding rules.</li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>8. Performance Issues</strong></h2>
|
||||
|
||||
<ul>
|
||||
<li>Reduce mod count.</li>
|
||||
<li>Check for heavy mods causing CPU spikes.</li>
|
||||
<li>Ensure your TrueNAS SCALE node has sufficient RAM.</li>
|
||||
<li>Review BepInEx logs for plugin errors.</li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>9. File Permission Errors</strong></h2>
|
||||
|
||||
<p>
|
||||
The <code>steam</code> user must own:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><code>/opt/valheim_base</code></li>
|
||||
<li><code>/opt/valheim</code></li>
|
||||
<li><code>/opt/steamcmd</code></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
If permissions break, restart the app — the entrypoint resets ownership.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>10. When All Else Fails</strong></h2>
|
||||
|
||||
<ul>
|
||||
<li>Restart the TrueNAS SCALE app.</li>
|
||||
<li>Restore from a backup.</li>
|
||||
<li>Temporarily remove mods.</li>
|
||||
<li>Check logs for BepInEx or SteamCMD errors.</li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
||||
<h2><strong>Next Steps</strong></h2>
|
||||
|
||||
<ul>
|
||||
<li><a href="Home">Home</a></li>
|
||||
<li><a href="Quick Start">Quick Start</a></li>
|
||||
<li><a href="Installation">Installation</a></li>
|
||||
<li><a href="Modding Guide">Modding Guide</a></li>
|
||||
<li><a href="Backup & Restore">Backup & Restore</a></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
This troubleshooting guide covers the most common issues. If problems persist,
|
||||
review logs carefully or restore from a known-good backup.
|
||||
</p>
|
||||
Reference in new issue
Block a user