Full Minecraft Server Troubleshooting Guide

HOW TO TROUBLESHOOT A MINECRAFT SERVER

Minecraft, although it has been out of beta testing for a long time, still can have its glitches at times. When you merge it with an external server wrapper such as CraftBukkit, Tekkit, and third-party plugins, most will eventually run into problems such as crashes, lag, errors and faulty plugins at some point.  Server problems are usually unavoidable with most Minecraft servers and the more plugins and the larger your world, the more likely you are to have these issues.  This guide is aimed to explain, in detail, the basics of troubleshooting your server so that you can narrow down to the root of the issue. 

One point we (Sapling Servers) would like to make is that server crashes and [most] causes of lag have nothing to do with the host themselves (this goes for any hosting company).  Every host runs the Minecraft/External Minecraft server software (which is a .jar file) through Java, which is cross-platform (Windows, Mac & Linux Compatible).  This allows all servers to run the same way as they would on one OS compared to another.  Due to this, it isn’t the host that is actually starting/running your server, it is the Minecraft/External Minecraft server software that is running on Java that is the brain of everything, the only time a crash is an issue on the host’s side is if their actual physical hardware breaks down or if the operating system crashes.  All other crashes are caused directly by Minecraft/External Minecraft server software and plugins themselves.  

You will also want to understand that host companies cannot fix all Minecraft related problems for you as we did not program the game, CraftBukkit, Tekkit or the plugins you use – we can only give you our best effort at debugging the problems using our experience.  User error is also something that is difficult for a host to fix since we did not configure your server nor did we install the plugins (exception being if you ordered the Plugin and Modpack Support addon), so you always want to provide as much detailed information as possible of how the problems started if you need help on these types of issues/problems. However, some problems may not be able to be resolved WITHOUT doing a whole reset/rollback. This is sadly the nature of the Minecraft game itself and the plugins based upon it. 

FIRST STEP OF ANY MINECRAFT SERVER ISSUES:

The first thing YOU, the server owner, should do with ANY kind of server problem is check your console or server.log file (via FTP or built-in file viewer).  The console is a realtime version of the server.log file (a txt based file), but the server.log file has a longer history since it is all the console log’s output that’s ever been listed, while the console display is limited to last several lines.  A lot of the messages will look unusual or cryptic in the console/server.log, but you can usually find the error messages containing the names of the plugins the error is related to.  Error messages are preceded by a tag such as, or similar to: “[SEVERE]”. Some errors will tell you exactly what the problem is, which makes it easier for you, the server owner to fix the problem. Though in some cases, the server.log file size will be in the gigabytes (1000MB+), which makes it impossible to open. Usually, when the server.log file is larger than 1 GB, it is due to chunk errors. 

Tip: Deleting your server.log file (without the server running) will make it much shorter/cleaner and easier to see startup and shut down errors.  It wouldn’t be fun to have to download and open a 100MB log file each time, you can rename it to another name (example: server.logOLD1) if you want to keep it. 

Once you are able to figure out the plugin(s) causing the problem, the next step is to make sure that all the plugins you have installed are up-to-date (including your Minecraft/External Minecraft server JAR by using the update button in the Multi-craft panel).  This should clear up most, next to all plugin related errors, but if you are still getting errors after updating your plugins, then they can be related to other issues, which will require further investigation.

REMOVING THE MINECRAFT WORLD AS A SOURCE OF THE PROBLEM:

Sometimes, the problem is something within the world itself.  To test this, you will want to go into your multi-craft panel and change the “level-name” setting (default is “world”) to something else (“world2”), then hit the save button and then allow the server to automatically restart.  This will create a new world folder in your server’s directory called “world2” (Or other names if you chose a different name) and will be a plain, automatically generated, no user-input world. Check your server.log file to see if the same errors come up. NOTE: Changing your level-name might interfere with how multi-world plugins work (you may also have to remove the world we just created from the multi-world plugin(s) config file, otherwise the world will automatically be generated again.)

If this eliminates the issue on your server, then it means that something in your world file is causing an issue.  This can be but is not limited to: water, Redstone, lava, large quantities of mobs, non-removal of dropped items et cetera.  You can also check to see if your plugins keep throwing errors in your server.log file or console.

To change the world back to your old one, simply change the world-name back to whatever it was before (capitalizations and spaces matter, so type it in exactly the same as before).

BASICS TO FIXING MINECRAFT PLUGIN PROBLEMS:

In most cases, plugin errors are caused because they are incorrectly installed (example, some plugins require other plugins to be installed to work) or they are out of date.  You ALWAYS want to make sure that your Minecraft/External Minecraft server file is updated to the latest recommended build (from the game panel), and that the plugins you install support the same version of the Minecraft server software you use.  Differences in these versions/different types of server software can cause errors, lag, and crashes.  It is usually best to simply not install a plugin that doesn’t support the latest CraftBukkit. Plugins can sometimes be updated frequently, so you will always want to check on http://plugins.bukkit.org for the latest versions of your plugins. 

If updating does not remove the errors, then it is likely an issue with your config file.  Some plugins require things such as a MySQL database (which Sapling Servers can provide by request), and if you don’t enter in your MySQL database login info, then the plugin will throw errors.  Other issues with plugin configs can come from outdated config files used with an updated version of the plugin, so you will need to remove the config file, then restart the server so the plugin automatically generates a new config file for it.  

Some plugins also have data files that can become unusable, in some cases, the data files can be manually edited to fix the problem, but you may end up having to remove (or rename) the entire data folder for the plugin to fix the issue.  Many causes of errors outputting from configs are in the .yml files (config files extensions are .yml).  Those have a VERY, VERY specific format that you must follow no matter what. Failure to do so and getting even just a capitalization error will make the plugin and all associated plugins unusable. You can check the syntax of any .yml file using this site: http://yaml-online-parser.appspot.com/

TYPES OF MINECRAFT PLUGINS THAT CAN CAUSE LAG:

The following plugins are some (but not limited to) that can cause server lag:

• Anti X-Ray (or any x-ray related plugin)
• World Edit (and WorldBorder)
• NPC (too many NPCs)
• Anti-cheat
• Wrong version of anti-lag plugins
• Out of date/wrong version of plugins in general
  

THE PROCESS OF ELIMINATION:

One of the best ways to test for server errors is to disable plugins in groups to begin narrowing down the issue to a single plugin while making the process faster of course.  This is simple, a good way to do this is to append .disabled onto the plugin file name, (example) world edit.jar.disabled.  When it’s time to re-enable the plugin(s), just remove the .disabled from your plugin(s) and restart the server.

WHAT TO DO IF YOUR MINECRAFT SERVER DOESN’T START UP:

There are a few causes of why a server won’t start up (at all), so we’ll go over a few here.

1. You have no more disk space available, check the profile page in your multi-craft to confirm that you may/may not have reached the limit. This is common if you have backup plugins that you don’t keep track of and it creates hundreds of backups, thus using up all of your disk space.  If you don’t need something, remove it.
2. You have chunk errors.  Chunk Errors spam error messages into your server.log file and makes it max out your disk space.  Since the server.log file holds all error messages it can increase into the gigabytes in size.  You will want to delete your server.log file in this case and may need to load a new world sadly. 
3. Your Minecraft server JAR file is corrupt/unusable. You can upload the latest version using the update button in your multi-craft panel.
4. There is a plugin that stops/crashes the server upon start up, to fix this, read above on ‘The process of elimination’ to start using your server once again. 

TYPES OF LAG:

There are different types of lag that can mean different things on your server.  We’ll go over a couple here:

1. Delayed block breaking, movement lag (you get moved slightly backward in time after walking a certain amount of time or distance, which is also known as “rubber-banding”, and damage delay.)

• This type of lag can usually happen due to network lag (on the hosts or the client side), lag on the client’s own internet connection, server runtime/performance issues that can happen from plugins/world(s), and the use of external MySQL databases for plugins.  One way to determine if the lag is coming from your world/plugins is by using a plugin called “LagMeter” (or another similar plugin) and using the /lag command when you feel lag.  If the TPS is near 20, then the issue is related to other things. 

1. Simply cannot (or hardly) look around – framerate issue on the client side.

• This type of lag is usually caused by something wrong with the servers chunk generation.  It can also be caused by TNT explosions and damage to chunks caused by TNT.  A new world may be required if this type of lag lasts longer than a few minutes, or continues to occur after relogging into the server.  This type of lag can also come up from using ore obfuscation or anti x-ray types of plugins.  The only solution to that would be to update the plugin or to simply remove it. Many servers have also disabled TNT in the world all together (not best for faction based servers).

IN CONCLUSION:

If you are experiencing some form of error or lag on your server and are unable to determine using this article, please feel free to open a ticket with our Technical Support team  Please include as much detailed information about the situation as well as outlining any troubleshooting procedures you have completed on your own to have your issue resolved as quickly as possible. Without detailed information on the issue, or on troubleshooting you may have already done, our tech support team would start from the most basic troubleshooting procedures and may be repeating what you have already completed.