Basic tModLoader Usage FAQ
This Guide has been updated to 1.4. If you need to view the old 1.3 version of this wiki page, click here
This guide will attempt to help users fix many common issues. Please search through this document for the error you are experiencing. You can use ctrl-F to use your web browser to search this page for a word (such as an exception name or error message). If you can't find anything relevant, please try all the suggestions in General Troubleshooting Steps. If nothing there helps, you can pursue direct support in the Getting Support section. Do note that this guide mostly concerns issues with tModLoader itself. If you have an issue with a specific Mod or combination of Mods, see Mod Troubleshooting Steps
Please do not attempt to install "tModLoader 64 bit" into tModLoader, it is no longer useful and will prevent the game from launching correctly. If you have previously installed it and are experiencing issues, your first troubleshooting step is to do a fresh install. You will also need to clear out the Launch Options by following these instructions.
If you pirated Terraria, we can't help you. tModLoader won't work. Please don't bother us by asking how to get it to work.
These steps should be followed if your specific issue is not found in the later sections of this guide.
If you are on 1.4.4-preview tModLoader, there is a greater possibility of tModLoader breaking, so you should switch back to None (Stable tModLoader) to see if that solves your problem. Conversely, sometimes bugs are fixed in 1.4.4-preview, so you can switch to 1.4.4-preview from None to test and see if the upcoming monthly release has a fix for your issue.
Switching tModLoader branches
In Steam, right click on
tModLoader, selectProperties, selectBetas, then select1.4.4-previeworNonein the dropdown. Ignore the access code section. Close the Properties window, you should see tModLoader downloading an update, once it finishes you can launch it.
If you switched to
1.4.4-previewand your issue is resolved, remember that1.4.4-previewis mostly for mod makers and testers and you may find that some mods you use are now broken. The fixes being tested in1.4.4-previewwill arrive in stable tModLoader near the start of each month (unless there is an extended preview window). If you can avoid the issue, waiting until the start of next month might be better than staying on1.4.4-preview.
Verifying game integrity will restore all files installed by tModLoader in the install folder to their original state. In Steam right click on tModLoader in the library, then click on Properties click on Local Files. Click on Verify integrity of game files.... (Video instructions). This should start a download of the now missing files. Once that is done, try tModLoader again to see if you issue is resolved. If it isn't, or you are on GOG, follow the Fresh Install instructions.
tModLoader loads files from the Terraria install folder. Do the same steps above but for Terraria.
A fresh install solves many issues preventing the game from launching. After doing a fresh install, do not place any other files in the install directory. First, open up the install location.
Make sure you opened the install folder, not the saves folder. The saves folder has folders named "Players" and "Worlds" while the install folder has folders such as "tModLoader-Logs" and "LaunchUtils". Now that the install folder is open select all the files and folders and delete them all. Next, reinstall tModLoader:
- Steam install: In Steam right click on
tModLoaderin the library, then click onPropertiesclick onLocal Files. Click onVerify integrity of game files.... This should start a download of the now missing files. In the install folder, you should see the files start to appear again. - GOG install: Install as normal, to the same folder as before.
tModLoader loads files from the Terraria install folder. Do the same steps above but for Terraria.
If you are experiencing an issue, it is useful to confirm whether the issue is caused by a Mod or by tModLoader. Usually the cause of issues can be determined by reading the error messages in-game or by Reading client.log, but if not, disabling all mods and confirming that the issue still happens or doesn't happen is useful.
First, visit the mods menu and click disable all (if your issue is preventing you from getting to the main menu, you can either hold the shift key while the game is launching to skip loading mods or find "enabled.json" in the Mods folder in the saves folder and delete it). Close tModLoader and launch it again. Attempt to replicate the error you experienced before. If the error still happens, it is a tModLoader issue and you should try Getting Support. If the error doesn't happen, you will need to use the Flowchart to identify the mod causing the issue. After
Resource packs can cause issues, disabling all resource packs and then testing again can rule out the resource packs as being the issue. To disable resource packs, you can visit the Workshop->Use Resource Packs menu and disable all packs. If you can't get to that menu, close the game, open up \Documents\My Games\Terraria\tModLoader\config.json in a text editor, find the "ResourcePacks" section, then change all true to false, save the file.
The config.json holds user preference information. Sometimes a buggy value in it can cause issues. You can delete or rename the file to reset preferences to default values to test if it was causing your issue. Open up the saves folder and find config.json. Rename config.json to configOld.json. Renaming it lets you restore it later if you want. When you launch tModLoader, you should see the Select Language menu, if you don't, you might have edited the wrong file. If doing this doesn't change anything for your issue, you can close tModLoader and rename the file back to config.json after deleting the newly generated config.json.
You can do the same for the input profiles.json file if your issue is related to keyboard, mouse, or gamepad issues.
Sometimes a mod is causing issues, but you can't tell which mod is the problem. Use this flowchart to diagnose and determine the bad mod:
Most bugs in tModLoader will appear as errors logged to the client.log file. Read the file to find mods that are potentially causing bugs.
- Close tModLoader, then reopen tModLoader and repeat the steps necessary to trigger the bug.
- Open the
client.logfile in a text editor, such as notepad. Theclient.logfile is found in the logs folder- To easily open the folder copy
%UserProfile%\Documents\My Games\Terraria\tModLoader\Logs\to the clipboard withctrl-cand paste it into the address bar in the file explorer withctrl-v. Press enter and the file explorer will go to the folder.
- If a window pops up asking "How do you want to open this .log file?", find Notepad in the list, click it, click OK.
- To easily open the folder copy
- Scroll down until you see the first exception in the file. It should look like the image below. Look for indentation followed by the word "at", these lines are the details of the exception. Each exception like this in the log is caused by a bug.
- Look through the exception to find the names of mods you have enabled. The first word after "at" on the lines and before the period is where the names of mods involved in the exception will be shown. Words like "Terraria", "Microsoft", and "MonoMod" can usually be ignored. In this example, the mod named "GadgetGalore" in the exception and is likely a broken mod.
- If there are multiple mod names in a single stack trace, either mod could be at fault, or both, you'll have to do some testing.
- After finding a mod in an exception, disable it the next time you launch tModLoader and see if the same bug triggers. Repeat the above steps if there are additional mods that are causing bugs.
- If you need help reading your client.log, you can ask for help in the support-forum channel on the tModLoader Discord chat.
Many errors you might experience while playing tModLoader can be identified by reading the client.log file. (If you are experiencing an error that only happens in multiplayer, you'll need to read both client.log and server.log). By properly reading the log file, you can identify if an issue is caused by a bug in tModLoader or a bug in a mod you are using. Since tModLoader updates to new versions every month, a mod that worked yesterday might be broken today. In any case, the logs are a good place to find the issue.
If you are experiencing a bug, first make sure all mods are up to date, then close tModLoader and reopen it. This will reset the log and make it easier to read. Once you experience the bug, close tModLoader and open the log file. The log file is the client.log file found in the logs folder. Open the file in a normal text editor like notepad if it doesn't have a file association already.
Next, you'll want to look through the file looking for words like "error" or "exception". Using ctrl-f to use the Find feature of your text editor. You'll typically want to focus on the earliest error you can find in the log file. Errors that come after earlier errors might be caused by those earlier errors, so fixing the earlier errors might fix the later errors. Once you find the word "error" or "exception", you should see something similar to this:
In the above excerpt from client.log, we can see an error is being logged. The error begins at line 41, with a brief summary on line 42 shown in blue. After the error summary, there will be a "stack trace" that shows where in the code the error is happening. Take note of the indentation of the lines of the stack trace, shown in green. This indentation is very useful for quickly finding errors logged in the log file rather than using crtl-f. Next, you'll want to look through the stack trace for the names of mods you have enabled. The first word after "at" on the lines and before the period is the key word you'll want to look at. Words like "Terraria", "Microsoft", and "MonoMod" can usually be ignored, you want to find the mod or mods that show in the error. In this example, we see a mod named "GadgetGalore" in the stack trace and can make the assumption that it is the cause of the error. If there are multiple mod names in a single stack trace, either mod could be at fault, or both, you'll have to do some testing. Now that we found a mod that is erroring, you can disable the mod and try again. Not every error logged in the logs will an actual bug, so some experimentation may be required. If you need help reading your client.log, you can ask for help in the support channels on the tModLoader Discord chat.
If everything in this guide fails to solve your issue, you may need direct support.
Support issues fall into two categories: Issues specific to a mod and tModLoader Support
If you need basic support to get the game running, see Discord Support, otherwise start at GitHub Issue Tracker
If your issue is not solved by this guide and you still need help first check the tModLoader Issue Tracker and search for your issue to see if it has already been reported. If you find your issue, please add a 👍 reaction to the issue to help us prioritize issues. To add the 👍 reaction, click on the smile icon on the top right, then click on 👍:
It might also be useful to add a comment to the issue with client.log and other useful information you can provide to help identify the cause of the issue. There might also be a workaround in the comments that you can follow to fix the issue on your end.
If you do not find your issue in the issue tracker, you should visit the #support-forum channel on the tModLoader discord. Discord is a free chat service you can access in your browser. We will not provide support for support issues here on GitHub. Once you find the #support-forum channel, make a new thread and describe your issue. You'll also need to post all your logs by opening up the logs folder and dragging the files into the chat. (Video example). Someone there should be able to help you.
If a specific mod is causing your issue, you should visit the mod's workshop page. Read the Description and see if the mod maker has a preferred contact method for bugs, such as a GitHub or Discord. If there is one, use it. If not, making a comment on the workshop page with your issue should let the creator know. If the bug is game-breaking, you will have to disable the mod or wait for it to be fixed by the author.
This message is a boiler-plate message, it is purely informational. If the version starts with v0.X, then you are trying to load a legacy mod and it won't work, you need to delete the mod and find it or a replacement on the current mod browser. If the version starts with v202X, then you should look at the next paragraph in the error message for the real error. If multiple mod names show up in the error, it may be a mod incompatibility. The author will be able to figure it out.
If you see this, the mod might be out of date. tModLoader updates every month and sometimes those updates will break mods. If it is the start of a month, the author might just be slow in updating. You will have to disable this mod until it is fixed. If you manually installed a mod, the mod will be purple on the Mods menu and you should delete it and use the workshop version.
Follow the instructions in the next section.
There are a variety of issues that can cause this issue. If none of these suggestions work, please come to the tModLoader Discord Support
Launch tModLoader Manually
Sometimes launching manually can bypass certain launch issues. Open up the tModLoader install folder and double click on "start-tModLoaderServer.bat". If this works, you should still try to fix the issue through other steps here or in tModLoader Support since launching this way is inconvenient.
Fresh Install
Follow the Fresh Install and Fresh Install Terraria steps. This may seem like a lot of effort but it solves a large portion of issues.
Delete dotnet folder
Deleting the dotnet folder in the tModLoader install folder might help. If the issue persists, check that your antivirus isn't quarantining any of the files. The dotnet\6.0.0\shared\Microsoft.NETCore.App\6.0.0 folder should have 223 items in it. If it doesn't, ensure that your OS is 64 bit and install the dependencies listed for your OS before deleting the dotnet folder and trying again.
Note: If your console window indicates that it is having trouble downloading dotnet on GOG, then you can manually download dotnet 6.0.0 and place it in the LaunchUtils folder in the install folder. The file should be named dotnet-runtime-6.0.0-win-x64.zip. Delete the dotnet folder once again and try launching again.
If you are still having issues, and dotnet\6.0.0\dotnet.exe or the mentioned 223 files are not all there, you can manually install the included dotnet. Delete the dotnet folder, then make the dotnet folder again and open it. In that folder, make a folder named 6.0.0 and open it. In a separate file explorer window, open the LaunchUtils\dotnet-runtime-6.0.0-win-x64.zip file, you should see 2 folders and 3 files contained within. Drag all of those folders and files into the 6.0.0 folder you created earlier.
If you are still having issues with dotnet, some users have reported that installing the dotnet sdk to their computer after deleting the dotnet folder fixed the issue. Our guess is that the full installer fixes some issues that were preventing our installer from working.
Check Natives.log
In the logs folder, open up Natives.log. If it says "An assembly specified in the application dependencies manifest (Microsoft.NETCore.App.deps.json) was not found" or something similar, double check that you followed all the steps in Delete dotnet folder suggestion above.
Disable Proton
Do not use Proton on Linux, it will not work. If you did, you'll have to Delete dotnet folder after disabling Proton for tModLoader.
Check launch.log
Open up launch.log found in the logs folder. If the word "FAudio" shows up in your log, you might want to try the IAudioClient-workaround.zip
Disable RGB Keyboard Features
Even if you don't think you have RGB keyboard, this can help. Follow the RGB Keyboard Bug (Port 53664) instructions.
Restart Computer
Restarting the computer solves many issues tModLoader users face. It may seem trite, but it works, give it a try.
This is usually solved by restarting the computer after confirming that you have switched to the None branch for tModLoader and verifying game integrity, and following the next section.
This is caused by previously installing tModLoader 64 bit. First do a fresh install if you haven't already, then right click on tModLoader in Steam and select Properties. Make sure Launch Options is completely empty, then close the window.
This is usually caused by your Terraria install being out of date. First, launch Terraria and confirm that it is updated to the latest version by looking in the bottom right corner. Next, follow the Verify Game Integrity Terraria instructions. If this doesn't solve the issue, it might be a mod causing this issue.
If you are on Windows 7, you'll need to install the directX package from Microsoft. Restart your computer after running and finishing the installer.
This is caused by an incompatible resource pack. Currently some resource packs are incompatible with tModLoader. To fix this, open up \Documents\My Games\Terraria\tModLoader\config.json in a text editor, find the "ResourcePacks" section, then change all true to false, save the file. Now tModLoader should launch again.
Solution. Disable BitDefender or disable the Safe Files feature of Bit Defender. Some more info has been collected here.
This is most likely related to your antivirus blocking access to the tModLoader folder in the Documents directory. See the below issue for the process (but do this with the folder instead of the exe)
If you try to install tModLoader through Steam and it gives you a message with "Disk Write Error" in it, it is usually caused by Avast. Disable it temporarily and install tModLoader.
Controlled Folder Access is a Windows 10+ security feature intended to prevent ransomware. It is a useful feature, but it will get in the way of tModLoader saving files to the Documents folder where game save files are typically installed. If you have this feature enabled, you can add an exception to tModLoader to allow it to work. You can also just disable the feature completely, but don't do that unless you know what you are doing.
Adding an exception
The easiest way to add an exception for tModLoader is to press OK on the error, then click on the notification that appears:
- If the notification doesn't appear within 5 seconds, you can visit the action center at the bottom right corner of the screen and find it there. If it is not there, search "Controlled folder access" in the start menu, click it, then click "Block History"
Click on the first result:
Click Yes when asked "Do you want to allow this app to make changes to your device":
You should now see information explaining that "dotnet.exe" was blocked from accessing the "My Games\Terraria\tModLoader" folder:
Click Actions and then Allow on Device:
You will once again be asked "Do you want to allow this app to make changes to your device", click Yes:
tModLoader should now be able to create the save files it needs. Launch the game again.
This issue can be caused by your antivirus or windows security settings. If you're using Windows Security (formerly Windows Defender) and are getting this error, then you will need to add "dotnet.exe" to your whitelist, for further instructions on how to do this continue reading below.
(If you follow the directions below and still can't solve the issue, a last resort is to tell tModLoader to save to the install directory instead. You can do this by creating a savehere.txt file in the install directory.)
Adding "dotnet.exe" to your whitelist
Right-Click Windows Security in your system tray and select "View Security Dashboard"
Left-Click "Virus & threat Protection"
From there, Left-Click "Manage settings" under "Virus & threat protection settings"
Scroll down until you find the "Controlled folder access" section, and then left-click "Manage Controlled folder access"
Left-Click "Allow an app through controlled folder access"
Left-Click "Add an allowed app", and select "Recently blocked apps"
Scroll through the list until you find "dotnet.exe", and click the + and then close, after this you're done! (If you cannot find "dotnet.exe" on your list, then continue with the below steps)
Back in the "Add allowed app" selection, left-click "Browse all apps"
Navigate to the tModLoader install folder and then navigate to and select "dotnet/6.0.0/dotnet.exe", then press Open. This will add the file to your whitelist. Done!
Try the IAudioClient workaround.
Audio issues are particularly hard to identify, try these troubleshooting steps if your issue is not listed. For each of these make sure tModLoader is closed while you try these changes:
Fresh Install
Manually installed wave banks can cause issues, following the Fresh Install and Fresh Install Terraria steps will ensure that those files are removed. You might not remember manually installing wavebanks, but other things like installing tModLoader 64 bit could do this incidentally.
Disable All Resource Packs
Follow the Disable All Resource Packs instructions.
Change audio devices
For example if you are using headphones, switch to your speakers. If you don't have speakers, try plugging some in. Try launching tModLoader.
Unplug Controllers
Some controllers have speakers in them that might be causing issues with our audio playback code, try unplugging them and then launching tModLoader.
Reset config.json
Follow the Reset config.json instructions.
Try the IAudioClient workaround
Try the IAudioClient workaround.
Set Volume to 0
If audio issues prevent the game from launching, open up the saves folder and find config.json, open the file in a text editor. Find "VolumeMusic", "VolumeAmbient", and "VolumeSound". For each of these, change the number to 0. Save the file. If this works, the issue is audio related, other steps in this guide might be able to restore audio so you can turn the volumes back up.
When the game stops responding, that is indicative of the game logic being stuck in an infinite loop. This type of issue can be very hard to diagnose. A capable programmer can use a minidump file to investigate the cause of the issue. If the issue is in a mod, hopefully that modder will fix their mod, if it is in tModLoader we can work on fixing it.
If your tModLoader stops responding and goes white, you can provide us with a minidump file and it will help us debug the issue.
Expand for Minidump Instructions
To do this, download https://download.sysinternals.com/files/Procdump.zip and extract the zip. Open a command prompt in that folder by typing
cmdin the file explorer address bar and then pressing enter.
This will open a command prompt:
Next, open task manger by pressing ctrl-shift-escape. Click Details, then scroll down to the dotnet.exe that is Not Responding:
Take note of the PID. In this image, it is 20680, but yours will be different. Go back to the command prompt and typeprocdump.exe -mm 20680, except change 20680 to your number. After a few seconds it will be done:
Back in the file explorer, you can see the .dmp file:
Find some way of uploading this file to us on the Discord support channel. We have nitro boosts so you should just be able to drag and drop the file into the support thread.
You can skip loading mods by holding shift while tModLoader is loading until it reaches the main menu. Visit the Workshop->Mods menu to disable or delete the mod. If you need to directly delete a mod, you can unsubscribe on the workshop. If you need to delete a manually installed a mod, open up the tModLoader mods folder and delete the offending .tmod file.
(Also applies to "Cannot access a disposed object" errors)
This error is an error usually caused by an unhandled error in a mod. This makes it hard for users to know which mod is broken. Much of the time this error will only happen after reloading mods (improperly unloaded Texture2D references), but it can happen due to other errors (for example, dividing by zero.) As a user of mods, it can be hard to figure out which mod is causing the issue. To determine the broken mod, follow the steps in Reading client.log. The mod causing the error causing this crash should be in the last or second to last entry. If you find a mod mentioned in one of those errors, that is likely the mod causing the error. If in doubt, ask in #support-forum on the tModLoader discord. As a last resort, use the flowchart.
This error means that tModLoader does not have enough RAM to load all the mods that you are trying to load. Large mods that add lots of items are the main culprit. You may have to cut down on the number of large mods you are trying to load at the same time. You can also try loading Small or Medium worlds instead of Large. Another possibility is that you have other large programs running. If you can close them, do so. Press Ctrl+Shift+Escape to bring up the Task Manager. In the Task Manager's Processes tab, look for processes that take up a large amount of memory. Anything taking more than 100,000 K is a good candidate. Also make sure that you are on 64 bit Windows and that you actually have more than 4 GB of RAM.
Viewing Mods that use a lot of Memory:
If you are curious which mods are using your limited Ram, you can enable the "Show Mod Memory Estimates" option in Settings->tModLoader Settings. After enabling the setting, you will have to exit to the main menu and then close and reopen the game for the setting to take effect. Visit the Mods menu, make sure you enable and reload the mods you are curious about, and you should now see colorful graph at the top that shows how much memory each mod is using. Use this information to disable mods that take too much ram compared to how much you enjoy the content.
This means that you migrated a player or world from a version of Terraria newer than the version of Terraria your version of tModLoader was built for. When Terraria updates, it takes a while for tModLoader to update, you'll have to be patient and wait for tModLoader to update to use that player or world.
This means that tModLoader can't load the player for some reason. We are constantly looking into causes of this. To fix this issue, you'll need to restore the player from a backup. If you notice that your player consistently corrupts after restoring backups, it may be a broken mod. You can try Getting Support, someone may be able to diagnose the issue.
tModLoader saves are kept separate from vanilla Terraria saves. You can copy back and forth between save locations, but be aware that you will lose Modded Tile and Items if you use tModloader worlds/characters in vanilla.
Solutions: To copy from Terraria to tModLoader, use the Migrate individual players... button in the tModLoader player and world select menus. Note that if tModLoader is currently not up to date with Terraria, the players and worlds will be too new to open. Also note that files stored on the cloud will not show up, you'll need to take the file off the cloud first, see below.
To migrate a player or world from tModLoader to Terraria, you'll need to copy from the tModLoader saves folder to the Terraria saves folder. (The Terraria saves folder should be the parent folder of the tModLoader folder.) For example, copy .wld files in \Terraria\Worlds to \Terraria\tModLoader\Worlds, and the same for the .plr files in the corresponding Players folders. For players you'll also want to grab the folder with the same name as well, since those are the maps.
Getting Players or Worlds from the Cloud
You may notice that your player or world isn't in the folder, or maybe only .bak files are in the folder. This means that you have put that player or world onto the cloud. There are 2 ways to get the files. The first option is to open Terraria or tModLoader and simply click the
Move off cloudbutton and then follow the above instructions. The second option is to copy the files from the local copy of cloud files steam keeps around and place them in their respective folder. These are found in the local cloud saves folder
tModLoader shares the cloud storage space with Terraria (about 150 MB of it). Exceeding this limit on Terraria + tModLoader combined will make you unable to move players and worlds to the cloud until sufficient storage is available. Easiest way is to "un-cloud" your vanilla Terraria worlds, they take up the most space. You can check how much storage is used in Steam: Right click tModLoader -> Properties, below the Steam Cloud section it says the amount of available storage. In the rare case where you used tModLoader cloud storage feature before steam release (0.11.7), you won't be able to get rid of these "orphaned" files the normal way. Try this method: Video, Terraria App ID is 105600.
Steam workshop sometimes goes offline for maintenance, try in a few hours or the next day.
If you find that you can't redownload a mod in-game, you'll need to close the game, then visit the tModLoader workshop. There, find the mod you are interested and subscribe. If you are already subscribed, unsubscribe and then subscribe again. Finally, restart steam by fully closing it (Steam->Exit), then launching it again. You may also need to follow the Verify Game Integrity steps to force steam to redownload mods you subscribed to.
Networking issues (SocketExceptionFactory, WebException, HttpRequestException) addressed to port 53664 are caused by RGB keyboard support bugs. You can attempt to repair the installation of your keyboard software, or disable the feature. Even if you don't think you have RGB keyboard, this can help. Close tModLoader. Open up the saves folder and find config.json, open the file in a text editor. Find the "UseRazerRGB", "UseCorsairRGB", "UseLogitechRGB", and "UseSteelSeriesRGB" entries and change "true" to "false" for each of them, then save the file and finally attempt to open tModLoader.
There are many things you should try:
- First, make sure none of your mods are throwing errors in the log. See Reading client.log to see how to check logs for error messages from mods.
- Next, confirm that the issue happens even with 0 mods enabled.
- Try changing "Frame Skip" settings
- You can try a different graphics options. To do this, close the game and then in Steam, right click on
tModLoader, selectProperties, and then find theLaunch Optionsbox. Type/gldevice:OpenGLor/gldevice:Vulkaninto the box and close the window. Launch the game and check your frame rate. Do these same steps to try the other option. If these have no effect, remove them in the same manner.
- Come to tModLoader Discord Support.
If your mouse is invisible and still highlights buttons, you might be running into an issue with "Monect Virtual Controller". If your client.log has "Monect Virtual Controller" in it, follow these steps to uninstall that. Plugging in a separate controller has also been reported to fix this problem if you don't have "Monect Virtual Controller".
Another solution is to close the game, then edit config.json, found in the saves folder, in a text editor and change the "InvisibleCursorForGamepad" and "SettingBlockGamepadsEntirely" settings to false and then save the file.