Troubleshooting

Common Issues

This guide covers the most frequent problems and their solutions.

Connection Problems

Can't connect to server - Connection timeout

Symptoms: Client shows “Connecting…” then times out or shows connection failed.Common Causes:

Port forwarding not configured
- Verify UDP port is forwarded on your router
- Default port: 11000
- Check both router and server firewall
Wrong IP address
- LAN players should use local IP (192.168.x.x)
- Internet players need your public IP
- Verify IP hasn’t changed (dynamic IP)
Server not running
- Confirm server is actually started
- Check server console for errors

Firewall blocking connection

# Windows: Allow UDP port
netsh advfirewall firewall add rule name="Nitrox" dir=in action=allow protocol=UDP localport=11000

# Linux: ufw
sudo ufw allow 11000/udp

Solution:

Verify server is running

Check the server console shows: Server is listening on port 11000 UDP

Test local connection first

Try connecting from the same machine using 127.0.0.1 or localhost

Check port forwarding

Use an online port checker tool to verify your port is open

Review firewall rules

Ensure both Windows/Linux firewall and router allow UDP traffic

LAN discovery not finding server

Symptoms: Server doesn’t appear in LAN server list.Causes:

LANDiscoveryEnabled=false in server config
Client and server on different subnets
Firewall blocking broadcast packets

Solution:

# In server.cfg
LANDiscoveryEnabled=true

Alternatively, use direct IP connection instead of relying on discovery.Source: LANBroadcastClient.cs:99-109 - LAN discovery uses UDP broadcast on predefined ports.

Client connection failed without reason

Error: The client failed to connect without providing a reason whySource: Disconnected.cs:60Possible Causes:

Network unreachable
Port completely blocked
Server crashed during connection

Solution:

Check server logs for errors at time of connection attempt
Verify network connectivity with ping
Test with a different client/network
Check server CPU/memory usage

Version Mismatch

Client version out of date

Error: Client is out of date. Server: X.X, Client: Y.YSource: MultiplayerSessionManager.cs:68-72

case -1:
Log.Error($"Client is out of date. Server: {SessionPolicy.NitroxVersionAllowed}, Client: {localVersion}");
Log.InGame(Language.main.Get("Nitrox_OutOfDateClient")

Solution:

Update your Nitrox client to match the server version
Download from the official Nitrox releases
Ensure launcher is up to date

Server version out of date

Error: Server is out of date. Server: X.X, Client: Y.YSource: MultiplayerSessionManager.cs:74-79Solution:

Server host needs to update Nitrox
All players should use the same Nitrox version
Check release notes for breaking changes

Game version mismatch

Symptoms: Server won’t start or clients can’t sync.Solution:

Ensure Subnautica game is updated to latest version
Verify Steam/Epic didn’t auto-update one but not the other
Both server and all clients need identical Subnautica versions

Server Startup Issues

Port already in use

Error: Port 11000 UDP is already in useSource: Program.cs:425-484 - Server waits 30 seconds for port to become availableSolution:

Find what’s using the port:

netstat -ano | findstr :11000
# Note the PID, then:
tasklist | findstr <PID>

Close the other Nitrox instance or other application
Change the server port:
```
# In server.cfg
ServerPort=11001
```

If you change the port, update your port forwarding rules and tell players the new port!

Could not find Subnautica installation

Error: DirectoryNotFoundException: Could not find Subnautica installationSource: Program.cs:82-85Solution:

Verify Subnautica is installed

Check that Subnautica is installed via Steam, Epic, or other platform.

Set game path in launcher

Open Nitrox Launcher
Navigate to settings
Manually set Subnautica installation path

Check installation integrity

Verify game files through Steam/Epic if installation is corrupted.

Common Installation Paths:

C:\Program Files (x86)\Steam\steamapps\common\Subnautica

Server starts but immediately crashes

Solution:

Check log files:
%AppData%\Nitrox\logs\
Look for error messages in latest log file
Common causes:
- Corrupted save file
- Missing .NET runtime
- Insufficient permissions
- Out of memory

Try with a fresh world:

# Start with new save name
./Nitrox.Server.Subnautica --save "TestWorld"

Entity cache loading takes forever

Symptoms: Server stuck on “Starting to load all batches up front”Source: Server.cs:203-217 - Loads all 504,732 entitiesThis is expected behavior when:

CreateFullEntityCache=true

Solution:

Be patient - can take 5-15 minutes on first run
Only needs to run once (cached for future starts)
Disable if you don’t need it:
```
CreateFullEntityCache=false
```

After initial cache load, server saves entities and won’t need to reload on subsequent starts.

Gameplay Issues

Player stuck on initial sync / world loading

Symptoms: Client shows loading screen indefinitely when joining.Causes:

InitialSyncTimeout too low for world size
Slow internet connection
Large world with many entities

Solution:

# Increase timeout (default 120000ms = 2 minutes)
InitialSyncTimeout=300000  # 5 minutes

Source: SubnauticaServerConfig.cs:74-83

Players can't see each other's buildings

Causes:

Building desync
SafeBuilding=true rejecting builds
Network lag

Solution:

Try rebuilding the structure

Check SafeBuilding setting:

SafeBuilding=true  # Stricter, prevents glitches
# or
SafeBuilding=false  # More permissive

Restart both client and server if persists

Source: SubnauticaServerConfig.cs:123-124

Inventory items disappearing

Possible Causes:

Death without KeepInventoryOnDeath enabled
Network desync
Save/load timing

Prevention:

# Prevent item loss on death
KeepInventoryOnDeath=true

# More frequent saves
SaveInterval=60000  # 1 minute

PvP not working / players can't damage each other

Check configuration:

PvPEnabled=true

Restart server after changing this setting.Source: SubnauticaServerConfig.cs:129-130

Save & Data Issues

Save file corrupted

Symptoms: Server won’t load world, crashes on startup.Solution:

Restore from backup

Navigate to save folder and look for backup files:

%AppData%\Nitrox\saves\<WorldName>\backups\

Copy backup to main folder

Replace corrupted files with latest backup versions.

Verify MaxBackups is set

MaxBackups=10  # Keep 10 backups
DisableAutoBackup=false

Auto-save not working

Check configuration:

DisableAutoSave=false
SaveInterval=120000  # Must be >= 1000

Verify in server console:

Should see periodic “Saving world…” messages
Check startup message shows: Autosave: ENABLED (2 min)

Source: Server.cs:230 - Server logs autosave status on startup

Can't find save files

Save Location:

%AppData%\Nitrox\saves\

List all saves programmatically: Server automatically scans this directory on startup (Source: Server.cs:348-378)

Performance Issues

Server using too much CPU/RAM

Solutions:

Reduce save frequency:

SaveInterval=300000  # 5 minutes instead of 2

Limit max connections:
```
MaxConnections=25  # Lower if needed
```
Disable full entity cache:
```
CreateFullEntityCache=false
```
Clean up old world saves to free disk space

High latency / lag for players

Server-side:

Check server CPU/RAM usage
Reduce save frequency if constant stutters
Ensure server has adequate bandwidth

Network:

Test ping to server: ping <server_ip>
Check for packet loss
Ensure no other bandwidth-heavy applications

Client-side:

Verify client PC meets Subnautica requirements
Update graphics drivers
Lower in-game graphics settings

Log Files & Debugging

Finding Log Files

%AppData%\Nitrox\logs\server-[SaveName]-[Date].log

Source: Log.cs:91 - Log directory definition

public static string LogDirectory { get; } = 
    Path.GetFullPath(Path.Combine(NitroxUser.AppDataPath ?? "", "logs"));

Opening Log Folder on Crash

When server crashes, you’ll see:

Press L to open log folder before closing. Press any other key to close . . .

Source: Program.cs:498-509

Understanding Log Messages

Common log patterns:

# Normal startup
[10:30:45.123] [INF] Starting Nitrox Server V1.8.0.0 for Subnautica
[10:30:46.456] [INF] Server started (1.3s)
[10:30:46.457] [INF] Server is listening on port 11000 UDP

# Player connection
[10:35:12.789] [INF] Player 'JohnDoe' connected from 192.168.1.100

# Errors to watch for
[10:40:00.000] [ERR] Port 11000 UDP is already in use
[10:40:00.001] [ERR] Could not find Subnautica installation

Getting Help

Check Documentation

Review configuration and hosting guides for detailed explanations.

Gather Information

Before asking for help, collect:

Log files
Server configuration
Nitrox version
Subnautica version
Steps to reproduce

Community Support

Join the Nitrox community:

Discord server
GitHub issues
Steam discussions

Known Issues

Check the Nitrox GitHub repository for:

Open issues
Bug reports
Feature requests

Preventive Maintenance

Regular Backups

MaxBackups=10
DisableAutoBackup=false

Consider additional manual backups of important saves.

Monitor Logs

Periodically check log files for warnings or errors.

Keep Updated

Update Nitrox when new versions release
Keep Subnautica updated
Update server OS and .NET runtime

Test Configuration Changes

Before changing production server config:

Test on a separate world save
Backup before major changes
Document what you changed

Quick Reference: Common Error Solutions

Error	Quick Fix
Port in use	Change `ServerPort` or close conflicting app
Can’t find Subnautica	Set game path in launcher settings
Version mismatch	Update client or server to match versions
Connection timeout	Check port forwarding and firewall
LAN not discovering	Set `LANDiscoveryEnabled=true`
Slow initial sync	Increase `InitialSyncTimeout`
Save corruption	Restore from backup in saves folder

Get Started

Features

Guides

Development

Common Issues

Connection Problems

Version Mismatch

Server Startup Issues

Gameplay Issues

Save & Data Issues

Performance Issues

Log Files & Debugging

Finding Log Files

Opening Log Folder on Crash

Understanding Log Messages

Getting Help

Check Documentation

Gather Information

Community Support

Known Issues

Preventive Maintenance

Quick Reference: Common Error Solutions

Next Steps

Configuration

Hosting Guide

Build docs developers (and LLMs) love

Get Started

Features

Guides

Development

​Common Issues

​Connection Problems

​Version Mismatch

​Server Startup Issues

​Gameplay Issues

​Save & Data Issues

​Performance Issues

​Log Files & Debugging

​Finding Log Files

​Opening Log Folder on Crash

​Understanding Log Messages

​Getting Help

Check Documentation

Gather Information

Community Support

Known Issues

​Preventive Maintenance

​Quick Reference: Common Error Solutions

​Next Steps

Configuration

Hosting Guide

Build docs developers (and LLMs) love

Common Issues

Connection Problems

Version Mismatch

Server Startup Issues

Gameplay Issues

Save & Data Issues

Performance Issues

Log Files & Debugging

Finding Log Files

Opening Log Folder on Crash

Understanding Log Messages

Getting Help

Preventive Maintenance

Quick Reference: Common Error Solutions

Next Steps