Troubleshooting Guide
Solutions to common tModLoader problems and error messages
Quick Solutions
Try these common fixes first before diving into specific issues:
Restart Everything
Close tModLoader completely and restart. This fixes 50% of issues.
Disable All Mods
Disable all mods and enable them one by one to find conflicts.
Installation Issues
tModLoader Won't Start
Windows Solutions:
- Install .NET Framework 4.7.2 or later
- Install Visual C++ Redistributable 2015-2022
- Run as Administrator
- Add exception to Windows Defender/antivirus
- Verify Terraria installation integrity
macOS/Linux Solutions:
- Install Mono framework (6.0 or later)
- Check file permissions:
chmod +x tModLoader - Install required system libraries
- Try running from terminal to see error messages
Steam-Specific Issues
Not Appearing in Library
- Refresh your Steam library
- Check if download completed successfully
- Restart Steam client
- Verify you installed tModLoader, not just added to wishlist
Steam Workshop Not Working
- Ensure you're logged into Steam
- Check Steam community features are enabled
- Try restarting Steam in online mode
- Clear Steam download cache
Mod-Related Issues
Mod Conflicts and Crashes
Identifying Problematic Mods
- Disable all mods and start with a clean slate
- Enable mods one by one, testing after each
- When crash occurs, the last enabled mod is likely the culprit
- Check mod descriptions for known incompatibilities
Common Conflict Types:
- Recipe conflicts: Multiple mods changing the same recipes
- ID conflicts: Mods using the same item/NPC IDs
- Version incompatibility: Mods designed for different tModLoader versions
- Dependency issues: Missing required mods or libraries
Performance Issues
Low FPS Solutions
- Reduce graphics settings in Terraria
- Disable resource-heavy mods
- Close background applications
- Update graphics drivers
Memory Issues
- Limit number of active mods
- Increase virtual memory
- Close other programs
- Consider 64-bit system upgrade
Multiplayer Issues
Cannot Connect to Friends
Mod Synchronization
All players must have the exact same mods enabled:
- Same mod versions
- Same mod load order
- No client-side only mods on server
Common Solutions
- Host creates and shares a modpack
- All players download the same modpack
- Verify mod list matches exactly
- Restart both client and server after mod changes
Common Error Messages
System.DllNotFoundException
This error indicates missing system libraries.
Solutions:
- Install Visual C++ Redistributable (Windows)
- Update to latest Windows version
- Install missing system dependencies
- Run Windows Update
System.OutOfMemoryException
The game has run out of available memory.
Solutions:
- Reduce number of active mods
- Close other applications
- Increase virtual memory/page file
- Upgrade system RAM if possible
- Use 64-bit operating system
Mod Loading Errors
Errors when loading or building mods.
Common Causes & Solutions:
- Missing dependencies: Install required mod libraries
- Version mismatch: Update mods to latest compatible versions
- Corrupted mod files: Re-download and reinstall the mod
- Invalid mod structure: Verify mod file structure is correct
Performance Optimization
Improve FPS
- Lower Terraria graphics settings
- Disable lighting effects
- Reduce particle effects
- Use performance-optimized mods
- Close unnecessary background programs
Reduce Memory Usage
- Limit active mods to essential ones
- Avoid texture packs with high-res textures
- Clear mod cache periodically
- Restart game session every few hours
- Use mods designed for performance
Getting Additional Help
Discord Community
Real-time help from community members and developers
Terraria Forums
Official forums with detailed troubleshooting threads
GitHub Issues
Report bugs and search existing issues
How to Report Issues Effectively
Include these details when asking for help:
- tModLoader version number
- Operating system and version
- Complete list of enabled mods
- Exact error message (if any)
- Steps to reproduce the problem
- Log files from the Logs folder
Frequently Asked Questions
Can I use tModLoader with pirated Terraria?
No. tModLoader requires a legitimate copy of Terraria to function. We do not support or assist with pirated versions.
Will my vanilla Terraria saves work with tModLoader?
Yes, tModLoader can load vanilla Terraria worlds and characters. However, content added by mods will not be available in vanilla Terraria.
How do I update tModLoader?
Steam version updates automatically. For manual installations, download the latest version from GitHub and replace your existing installation.
Can I play online with modded Terraria?
Yes, but all players must have tModLoader installed with the exact same mods enabled. Vanilla players cannot join tModLoader servers.
Where are my mod files stored?
Mod files are stored in:
- Windows: Documents/My Games/Terraria/tModLoader/
- macOS: ~/Library/Application Support/Terraria/tModLoader/
- Linux: ~/.local/share/Terraria/tModLoader/
Still Need Help?
If you couldn't find a solution here, don't worry! Our community is here to help.