Crash Reports 101
Table of Contents
- Part 1: Introduction
- Part 2: Getting a crash report
- Part 3: Reading the crash report
- Part 4: Common crashes
- Part 5: Posting Guidelines
Why are you doing this?
When playing minecraft, occasionally it will close unexpectedly and crash. The most common cause of this behaviour is due to mods (bugs in the game can also cause crashes). Many people will encounter a crash then instantly post on the last recent mod installed topic "This made my game crash". As a modder I cannot stress how annoying this behaviour is, especially when an answer can be obtained by this person by reading and understanding why it happened. Now I know that a great majority of people are not very technically minded, that's ok. It is for these people I have made this post for.
I will try and keep technical jargon at a minimum and explain any that is unavoidable. Hopefully this post may take the burden of some modders who get bogged down with crash report posts so they can get back to doing what they love, creating mods for the community. Furthermore I will try and keep things a bit more light hearted as well as providing random "Brotips"
Why does Minecraft crash?
In my experience there are a couple of main reasons minecraft crashes
- Improper installation of a mod or API
- Incompatibilities between mods
- Some sort of bug in a mod
- Pre-existing bug in minecraft
There can be other "fringe" cases of crashes (eg faulty hardware or not enough RAM) but the above will cover 99% of crashes encountered.
Now I just want to say, please don't "blame" anyone for a crash. If it is due to an error in the modder coding (eg 2 or 3) cut them some slack. Most modders are not professional coders, they make mods for fun. If it is due to 1 (i.e. you made a mistake) just take a breath and re-read the installation instructions for both the mod and any APIs (as well as the rest of this guide).
Minecraft didn't crash, it only blackscreened. What Do I do?
I want to start with the TL;DR version black screen = crash.
Sometimes rather than coming up with a nice little crash report, Minecraft will just show a black screen (Possibly flashing up "Saving Chunks" first). This is also a crash, and you should follow Part 2 of this guide. Crashes are generally caused by either exceptions or errors. These may or may not be caught by Minecraft's internal error logger. If the error logger does catch it, you will be displayed with the minecraft crash screen, if not just a black screen. There are ways to obtain the crash report as detailed in Part 2 below.
The META-INF folder
I just want to digress a bit to discuss what the META-INF folder is. Essentially all you need to know is this needs to be deleted if you want to mod minecraft. If you don't really care why then feel free to move to the next section. If you are curious, read on.
A java jar file is just a zip file with an optional META-INF folder. Because jars are not just a collection of .class files and resources, extra information is sometimes required (or desired) by application developers. The META-INF folder is a place to store package and extension configuration data, including security, versioning, extension and services. In Minecraft the security is the reason it must be deleted. The META-INF contains a file called "MAJONG_C.SF". This file contains a little code for each file within the jar which can be used to check if any file has been modified or corrupted. Therefore this file must be deleted to prevent the security check if you want to edit any of the files within the jar.
Now this is a very basic description of the META-INF folder as I was trying to make it as easy to understand as possible. If you are still interested look up the .jar file documentation on the java website
Getting a Crash Report
Help! I don't know what to do
Ok so you have identified that minecraft has crashed. How do we get the crash report?
If you are lucky a nice screen would have popped up with the crash report right in front, if this is the case move on to Part 3.
The output should look something like this
The part you need is in the white box.
If no crash is displayed on screen there are ways of obtaining the crash report, so use one of the methods detailed below.
Crash txt files
Both Modloader and Minecraft Forge try and output any crash reports into folders. This should be the 1st place to check. Now you do have to be carefully because occasionally I get people posting the contents of one of these files that doesn't actually contain the crash log (i.e. not helpful). Don't worry if this is the case, I will detail in Part 3 how to read the crash report meaning you will know if you have the wrong file. If this is the case, try another method described below.
Note: When I refer to directories in this section, everything is relative to the .minecraft directory. I will assume if you are installing mods you already know how to find it (It is dependent on your operating system)
BroTip: In windows the directory can be easily found by pressing the windows key + 'R' and typing "%AppData" (without the "'s) in the run dialog and pressing Enter. This should bring up an explorer window withe the .minecraft directory somewhere near the top.
Modloader generally tries to output it's crash reports in a file called "Modloader.txt". The file should be located in the ".minecraft" directory. This will only be from the last run of minecraft (i.e overwritten on each run). This obviously will only be present if you have modloader installed (Minecraft Forge has a different way of reporting crashes).
BroTip: If posting from the Modloader.txt file make sure it actually contains a crash, I couldn't tell you how many times people post me the contents of their Modloader.txt file when there is no crash in there.
There is a folder that Minecraft Forge creates devoted to crash logs. The folder is located in the .minecraft directory and is called "crash-reports". Each crash will display the date/time of the crash as well as the describing if the crash was in the client or server. Another thing that should be mentioned about this file is that it is set out differently to other crash logs. The Forge crash logs will have the stack trace at the top and the header information below it (they also contain a "witty" comment).
BroTip: Try to avoid opening the forge crash logs with notepad on windows. Notepad does not recognise the newline character used (because it is quite crappy). Try opening it with wordpad instead (right click, go to open with and selected wordpad or "other programs" and find it).
Now because you are hear I am going to assume you are not very technically minded, therefore using the command line may scare you a little. I want to start with, don't be scared, the command line is a very powerful tool. Of course there are more "user friendly" ways, but the command line is quick and does not require downloading on any extra files. Now these do depend on your operating system so only read the relevant one below
- Open the command prompt by pressing windows key + 'R' and typing cmd in the run dialog (and press enter)
- Type "cd %AppData%" and press enter
- Type "cd .minecraft" and press enter
- Enter the following command
java -Xms1G -Xmx1G -cp Minecraft.exe net.minecraft.LauncherFrameBrotip This can be pasted by right clicking on the command line window and pressing paste
- Login, start minecraft & re-create the crash. The crash should be displayed in the command line window.
- Highlight the crash report in the window, right click and press copy.
Note: for this to work you must have java as an environment variable. Read more here
Warning I do not have an Mac computer so I have not tested this and do not know how user friendly the method is. These instructions are from the Minecraft wiki page
[*]Go to Macintosh HD/Applications/Utilities and open Console.app
[*]Run minecraft and when it crashes the java log will be added to the console, which you can then select and copy
- Open a terminal (on distributions such as Ubuntu/Linux Mint, this is done with Ctrl + Alt + T)
java -Xms512m -Xmx1024m -jar minecraft.jar
- Watch the console output. You can select and copy it after making the game crash.
Note: Your current directory MUST be wherever the minecraft.jar file is. If you are using linux I am going to assume you know at least basic command line functions.
MC Patcher can be a great tool for obtaining crash reports (personally I don't like it for it's HD patching capabilities because i don't like it's methods but that's just me). Start by downloading mcpatcher from here
This is what the default interface should look like.
For this purpose I recommend unticking all boxes before proceeding and DO NOT hit patch. Hitting patch will make MCPatcher run through it's patching routine, problem is this has been known to interfere with the proper running of some mods including Minecraft Forge. Pressing "Test Minecraft" (Red Arrow) will launch minecraft in offline mode. Recreate the crash. The output will be displayed in the "log" tab (Red arrow in the picture below)
Now the great thing about mcpatcher is that it actually tries to give you the deobscurificated class/method/field names in the crash report. This can be an unbelievable help to the author of the mod if you have found a new bug or incompatibility.
I have also developed a bat script to assist in the gathering of crash logs. Unfortunately I found a bug in it. I will correct the bug and upload it at a later date.
Reading the Crash Report
Ok so you have successfully retrieved your crash report so now we blindly post it on the last mod's forum page right?
Doing this could result in the modder (or others) politely telling you the problem, the modder not responding (they may be away or busy) or a very grumpy response (modder may have had a hard day and you are the 10th person posting the exact same report). In any case, most of the time by simply reading and understanding the error report you can solve the problem yourself much quicker and easier then posting and waiting for a response. Sometimes posting is unavoidable (maybe you found a new bug) but it really should be the last resort, not the first.
Now this section actually has a duel purpose, I am writing this both for users who receive crash reports to at least try and diagnose their problems but also for mod makes or just general good guys who are trying to help others with their crashes.
A crash report generally contains 2 main elements. Now these don't really have formal names, but I generally refer to them as either the header or the stack trace. Also depending how you got the crash log there may also be other information that has been output that was likely left over mod debugging code, this can generally be ignored (although may be useful for the mod author).
Please note in this section I may interchange the word error and exception. There are important differences between these but I don't think we really need to get bogged down by that right now.
The header generally appears at the top of the crash report, it will generally contain things like your version of minecraft as well as the mods you have installed. Just a quick note on this, if you got your crash report from the forge "crash-reports" directory, the header will appear at the bottom and be set out slightly different. It will generally contain the same information just set out differently.
Here is an example of a header from someone who posted a crash report on my mod topic that uses Minecraft Forge.
Now right away from this we can see that this user is using the 1.3.2 version of minecraft, has minecraft forge installed, is using Mac OS X (64 bit) is using java 1.6, has 2 mods other than Minecraft Forge/FML both of which were loaded successfully (in this case they are both 2 parts of the same mod). Furthermore because the author (me) is so awesome and put the version of minecraft required in the zip name, we can tell that he is using a mod that is designed for the minecraft version he is using. So far everything looks great.
Brotip: If you are super worried about privacy and do not want to post your username, remove that section of the crash report or start it out like I did above.
The Modloader styled headers are slightly different, However I do not have access to one on hand right now (I only mod with forge) but they also generally show similar information. Crashes may occur without either modloader or forge (jar mods only or bugs in the vanilla game), again these should show the minecraft version/java version/os etc but for obvious reasons will not show loaded mods.
The stacktrace is the main technical part of the crash log.
Here is an example (in this case it is the other half of the header posted in the above section)
Stack traces are always printed from most recent to the least recent step in the trace (kind of like your browser history is ordered from most recently visited sight to the site you viseted a long time ago). The first line will describe the type of error. Take note of this, it can help you diagnose most of the problems. In the example above this is
I will go into more detail about this error in the next section as it can be a common crash.
Brotip: When dealing with this remember "Google is your friend" googling the 1st part of the error "java.lang.NoClassDefFoundError" can help you diagnose the general cause quite easily. Going to the 4th result (which is the java documentation tells us that this means "Thrown if the Java Virtual Machine or a ClassLoader instance tries to load in the definition of a class (as part of a normal method call or as part of creating a new instance using the new expression) and no definition of the class could be found.". In other words something that minecraft or the mod thinks is there is not actually there. This could be improper installation or a corrupted file, but right away we know quite a bit about the error.
Under the error name is a whole heap of at (classname).(method).... These can also be quite important to modders as it gives us a way to backtrack through the error to hopefully find the root of it. Again the most recent is at the top and least recent is at the bottom. This can be handy for those even without a background in programing. Sometimes you can find the culprit quite easily by scanning through the trace. For example if you see "mine_and_blade" in any part section, it is a good chance that the Mine & Blade mod is likely the source (In one way or another) of the crash.
For those who have a bit of programing experience what the above trace tells us is that the method a in ayq class had an error, it was called by the a method in the Minecraft class which was called by the next one down and so forth.
Now when we see a "Caused by" that means what we have is a "Chained Exception". This is important because it is often the case that one of the fundamental exceptions underlying the last encountered exception is the real culprit that must be appropriately addressed. So in other words, these secondary exceptions may be just as important. I can not tell you when they are and when they are not because it really depends on the particular error report.
Causes of Common Crashes
So now we have the crash report and we have a very basic understanding of it, what now?
So now we have the crash report and we have a very basic understanding of it, what now?
I thought I would start with a few common crashes that we might encounter. Again, if this can diagnose your problem we have saved you some time (you don't have to wait for a response) and we are allowing modders to continue modding rather than diagnose and solve Evey error.
I wanted to start with the error I have been using in the examples above. Here is the full crash report
A NoClassDefFoundError is thrown whenever a java program can't find a particular class that it thinks should be there. The class will be displayed after the ':' as well as the package/folder it is contained in. In the example above that means that the class that cannot be found is called SoundSystem and it is located in the paulscode/sound package.
There are 3 main reasons this can occur listed below
- You have not installed a required dependency. This is probably the most common cause of this error. Most of the time you can guess the missed dependency by looking at the classname/package. One common one I have encountered is when people forget to install PlayerAPI. In this case the crash will display java.lang.NoClassDefFoundError: PlayerBase. Always go back and make sure you have installed all dependencies for a mod
- The next most common reason I have seen for this error is due to a corrupted file. This happens occasionally while downloading mods. Just try and re-download the mod or API and try again.
- The mod auther has not packaged a particular class file. This will generally mean that part of name/package will have something to do with the mod. Now this is more rare than the other 2 above because if a modder does make a mistake such as this they will generally address it quite quickly. Also remember that your 1st assumption should be a corrupt download (2 above) so try to re-download the mod 1st.
Now the error posted above was actually due to a corrupted download of Minecraft Forge. After the user re-downloaded Forge everything worked again.
The dreaded null pointer exception. The most common cause of this doosy is due to modder error. It can also be caused by incompatible mods or knock on effects from other errors but generally its because of dodgy code. Null pointer exceptions occur when java tried to access an empty object. Because the object doesn't actually exist, java will have a cry and break down. Mostly this can't be fixed by anyone other than the author of the mod(s) in question.
The only recommendations I can say for this is to
- Try and work out the mod causing the error by looking at the stack trace.
- Make sure you don't have mods that are known to be incompatible installed
- Check the forum page to see if anyone else has already posted this error, if so there may already be a solution in the works and there is little point in re-posting the same error (maybe just a "I got the same error as x") but there is really no point in posting the exact same error log
Sorry I don't have an example right now, but these errors can be quite varied. If anyone really wants one I will find one later (or generate one myself) and post it.
Block ID conflict
This happens when you install a mod that is trying to use the same block ID as another mod. They can be identified by the first error being java.lang.IllegalArgumentException: Slot xxx, where xxx is a number.
Here is an example
These are generally easy to fix, most mods have some sort of config file (generally in the config directory of the .minecraft folder) that is generated the first time a mod is loaded. A mod can customise the block/item ids used in this file. So your best bet is to find the offending block id and change it in one of the mods and try again. You may have to try a number of times to find free block ids. Also minecraft does have a limited number of block IDs available for vanilla/modloader the limit is 255 (the 1st ~ 150 or so are taken up by normal blocks) while Forge has increased this to a bit over 4000. I believe vanilla will increase this to 4000 but I don't think it is currently implemented.
Just a note, conflicting Item ids will not cause a crash, but these can be identified by items randomly changing to another item on startup/crafting.
Brotip 1: A tool such as TMI can be used to help identify free block ids. The TMI side bar interface displays the block id used by whichever block you are overing over.
Brotip 2: If you can help it, always change the block ID of the most recently installed mod. Blocks in your world will also change.
So I have a crash report, done basic diagnostics and I am ready to post, how should I post it?
I thought I would start with a basic checklist about posting crash reports.
- Obtain the crash report
- Make sure it is actually a crash report (i.e. has a java stack trace)
- Do basic diagnostics yourself (read the thread)
- Make sure it is not one of the common crashes seen here
- Identify the mod causing the error
- Try the mod on a fresh jar with only the required APIs, this will help determine if the problem is caused by an incompatability.
- Read the Troubleshooting/FAQ section of the Mod page to make sure it is not a common problem that can be fixed
- Read the known bugs on the Mod page to make sure your are not-reposting a known bug
- Read the Incompatible mods section to make sure that you are not using incompatible mods
- Read the last page or two to make sure someone hasn't recently posted the same report (no point in reposting unless you have more information to add)
- Do a quick search on the forum topic using the most recent error (eg java.lang.NoClassDefFoundError: paulscode/sound/SoundSystem) as someone else may have already posted the same error a while ago and it has since been solved.
- Post your error using the guidelines below.
Always remember that posting the error should generally be your last resort. You will generally solve the problem quicker yourself as a modder is not always online to answer questions. You may not get a response for a few days and you can't blame the modder for this. It is therefore in your best interest to at least try and solve it yourself.
Now before I start, if a modder has another way they like to describe an error report follow theirs. This is just a suggestion.
When posting an crash report having as much detail as possible is the key. If you write stuff that's not needed, who cares? But not having enough detail can be very annoying for those trying to help.
At minimum you want
- The crash report (the most important part)
- A detailed description of your problem (when did it crash, what were you doing in game etc). Again the more details the better, even if you don't think they are relevant. Better to be safe then missing an important detail.
- A list of mods APIs and patches used, sometimes this may not be needed as the might be displayed in the crash log, however sometimes not all are displayed. This includes APIs such as Minecraft Forge & PlayerAPI as well as patches like McPatcher or jarmods like Optifine.
- Generally the OS that you use is not needed, java is generally cross platform. Although some mods may not like some OS because of the way certain features are written. Use your best judgement on this (especially considering it may already be in the crash report).
- Any other mod specific information that might be required. This one really depends on the mod you are using and will mainly apply to very special cases\
- Be Polite, as a modder I am much more likely to be more helpful to someone who has both been polite and actually tried to do a little homework (i.e stuff on this post) then to someone who as not.
Brotip: Crash logs can be quite long. Always put them in a spoiler as this will tidy up the post a bit. A spoiler can be made like this
[spoiler] Paste crash log here [/spoiler]
If you do do this it might also be a good idea to also write what the crash was somewhere outside of the spoiler so it can be search for by other users easily.
An example post might look something like this
Hi <modders name>,
My minecraft crashed on startup with a java.lang.NoClassDefFoundError: paulscode/sound/SoundSystem.
I was using no other mods or APIs (other than those required by this mod) at the time. When I installed the APIs I used a fresh jar.
here is the crash report
The above is clear and concise and provides all required information.
Thank-you for reading this post. I hope this will help out anyone with crashes in the future. Also feel free to post links to this topic to anyone who requires it.
If you have any suggestions to add to it or to clean up anything please let me know.