How to read stack-traces, and troubleshoot your own plugins (by yourself)

Introduction:
It has come to my attention, recently, that a lot of new developers do not understand the true reason of a stack-trace: Trouble-shooting and bug testing.

Far too often, I see posts inside of Plugin Development of developers who want other devs to check their stack-trace, and then allocate the problem for them. Usually, this takes about 3 steps more than it should, as the helper typically needs to ask for the code, the line-number, and then one last follow-up question.

So, to help prevent this, I've written a short guide on reading a stack-trace, and finding out what's wrong based on the results (on your own).

Something rather important to note, before going into this, is that this guide is helpful to both developers AND server administrators alike. Yes, you heard me, this is useful knowledge to plugin-users as well. If you know how to read the errors of another plugin, you can post a much more in-depth bug report. Not only will this help fix the issue sooner, but you might gain a little appreciation from the developer (which is always good for feature requests)

Anyways, let's begin:

What is a stack-trace?
Well, essentially, this is a stack-trace:

As you can see, its what several people refer to as the server log, console log, error log, what have you. It's where everything is going to be broadcasted whenever something goes wrong with a plugin. As you can see, I do have an error with my ComPassionate plugin.

Let's talk about how to fix it:

How do I decipher a stack-trace?
Standard Response:
"Oh my gosh! An error! Dear lord, look at all the lines, I can't translate that gibberish! Time to go to the Plugin Development section and ask for help!"

Don't panic! Stack-traces are actually really easy to read! Let's take the last example, and focus in on the error itself. I will then talk about how to 'read' it.

Ok, when troubleshooting any error, there are a few simple steps you must follow:

1. Make sure that it's actually a problem with your plugin! Look for any class-name or variable that pertains to your plugin, and if you find a match, continue on!
   
   
2. Look for the actual error. These are typically found at the start of the stack-trace, but will sometimes be located towards the middle. In either situation, its not hard to find it!.
   As you can see, I have a Null Pointer Exception. This means that something, somewhere, is null (and I've tried to invoke a change upon it).
   
   For a list of all exception types, and what they mean, you can poke around here
   
   
3. Find the file that the error occurs in. These generally appear in (parentheses) NOTE: (They might look like "<, >" on Windows), and will always be named one of your plugin files! For instance, my error occurs in LocationUpdater.java
   
   
4. The last, and probably the most important step in trouble-shooting, is to note the line number! This will tell you EXACTLY where the error occurs at, and will help with a speedy bug-fix. These will always appear after the file (mentioned above). I have indicated that my error occurs on line 29.
   
   If this happens to be you:
   "OMG, I don't have line numbers! PANIC MODE ENGAGE!"
   
   Windows-->Preferences-->General-->Editors-->Text-Editors | Then check the 'Show line numbers' box.

   View-->Show Line Numbers

Additional Note:
Once you've followed all of these steps, anything after that exception will likely be useless, as it generally involves internal things that you can't change. I've crossed out all of this useless info with a red X.

Now that I know exactly where to look, what do I do?
This is the easy part! You do what you do best : code

I'll go ahead and post a picture of the actual error in my code, to show you that I knew exactly where to look (and found the error immediately)

As you can see, I went straight to LocationUpdater.java, scrolled down to line 29, and immediately saw that I was calling isDead() on an entity, without ever directly checking to see if it was null. I fixed this in 30 seconds, and moved on with my life! Hooray!

Additional Examples:

1. A stack-trace involving onCommand() -
   (This is the type of stack-trace that gives you the useful info half-way through. I mentioned it briefly, above)
   
   
   Note: Not my own stack-trace
   
   

   
   In any error that involves onCommand, the useful stuff is going to be after a bunch of gibberish. The key is to look for the 'Caused by:' , because that is where the info actually starts.If you look in the picture, you can see that there's a Null Pointer Exception. It's located in theboot.java, on line 67.

Conclusion:
Stack-traces can be a pretty scary thing, I get that! But once you learn how to properly decipher them, you'll find that fixing bugs by yourself becomes monumentally easier!

If you didn't know how to read a stack-trace before, hopefully you do now!
If you did, and just decided to read, hopefully you think its a good guide for starters!

Now get out there and trouble-shoot!
And stop spamming Plugin Development with stack-traces because you aren't quite sure how to read them!

Disclaimer: Some of the errors/stack-traces/snippets of code in this post were real products of my own stupidity. They did actually occur, and I did actually wait for them to occur (for use of this post).

No servers were crashed in the making of this guide--okay, maybe one.

As a side note, I can not get those double spoilers to go away, no matter what I try. :|

*thumbs up*
I hope people will read that (though I am too pessimistic to really believe that).

I'd like to think that the pretty-pictures I included, along with my Picasso-esque drawing skills would be enough for people to get the general idea.

The intro and conclusion are there just because they're an industry standard

It's not about the wall of text, it's rather about the "Hm, I might search the forum for helpful topics first, there already might be a solution to my problem."

great job, I hope that people new to java do read this as it is well laid out and could teach them a few things

In the long run, my goal is to get this stickied to prevent it from dropping. There just seems to be a lot of posts that went along the lines of this:

In any case, the post is a bit long to even be considered for stickying (in my opinion). However, if the Moderators find it 'worthy' (for lack of a better word), I can shape it up to their liking.

Try to select everything in the spoilers and click "Remove formatting" (next to font selection).

I know there is, that's why I've put a *like* on your post.

The length shouldn't be a criteria for a sticky in my opinion. It just matters that your topic is helpful to the general audience that visits the forum here.

Ack! Messed up post, give me a second!

EDIT:
Fixed the double-spoilers

@Grammar Troll
<3

Nice thread Hopefully people will read this at some point to aid themselves in fixing their errors; it's not that I don't like to help others, but it would be a lot better if the easier stuff was solved by themselves leaving us to help with the more complicated issues.

Everyone who would like to code in java(or another language) shoul know first how to read errors and fix them, not just try random changes in the code and think *Crap, the error is still here*

@Slash1987
My sentiments exactly. I love to help people in the development forums, but at some point, you have to push the bird out of its nest.

If you don't learn how to properly read a stack-trace, then you will never learn how to properly troubleshoot a plugin (which is CRITICAL for ANY programming profession) As a side note, its one of the reasons that I find HTML so frustrating: There are very little error logs to indicate what's gone wrong. You just have to poke around until you find it yourself.

@DrBoweNur

I'm the first one banging my head into the wall trying to decode those shitty stack-trace when i studied Java at University, but now I can easily find error throug the millions of line printend in my test server. The only error that still give me problem is "Cannot pass [random_event] to [random_class].... XD

Small Update:
Added extra paragraph to the intro, to help clarify that this is useful information for both plugin-users, as well as developers. (In the event that a non-developer happens to stumble across this)

Good job on this, i am sure it will help quite a few (by people linking to this when people have a stack trace)

this should be stickied

Really nice article Bowe, also + that you started with the null reference exception error. This is the most common exception in Java, especially when you interact with slots of any type.

My method of locating the reason for the exception is to look at all veriables and method calls followed up by a '.'
It is almost always the case that you tried to execute a member function in a null variable.

The first dot now has the main focus, b could be null. If this is checked and it still happens, getMaterial() could return null. Generally it is best to look from left to right when processing lines with an error.

Not sure if it adds something, just felt like posting it.

EDIT

If you ever end up with a stacktrace not leading to any plugin, and you are sure you are the cause, try looking at the native Minecraft coding

Nice tutorial, maybe add how to enable line numbering in the common IDEs.
Also you could add a stacktrace of an exception thrown in onCommand so people see that the important part is after the [CAUSED BY].

Adding to what [user]bergerkiller[/user] said, NullPointerExceptions can occur when you pass null to a method, too.
In this case your code isn't mentioned at the top of the stacktrace, but a few lines below.

.... And I finally actually understand those jumbled things :O Thank you soooo much!

I'm going to be toying with commands today for this exact plugin demonstrated here, so I'll try and be sloppy to produce a CAUSED BY error.

Also, I'll upload a screenshot of how to enable line-viewing. Thanks.

@bergerkiller
Yeah, 9 times out of 10, the exception will be an NPE. Every once in a while you'll get issues with async threads or command executions.

@Perdog
Glad it helped!

Sticky please? This is also one of those things people ask a lot on the forums, don't want it to disappear from plain view.

@bergerkiller
To my knowledge, moderators don't really come into plugin development all too often. In any case, I'm not about to beg for a sticky. Don't get me wrong, a sticky would be great...but as long as I have this post to link people to whenever they post stack-trace errors, I'll be content.

Added info on how to enable line-numbers, if you don't know already.

Good job! I thought about writing some "quick guides" (stack-traces, @Override and stuff like that) for quite some time, but I never got the patience for it.
I doubt that it will stop people from posting annoying stuff like you mentioned - even when this gets stickied -, but at least we have a decent thread to link to now!
Thank you, well described!

Side note:

It's actually not "<"s and ">"s, but "("s and ")"s surrounding the filename. Looks crappy on windows consoles, though
Just a little remark because I fail to find a bigger issue with that awesome tutorial

@Bone008
Thanks! Fixed that in the OP.
Oh Windows, you so crazy.

Updated post with an additional section (for additional examples, go-figure).

Got an example of the onCommand() stack-trace that you were talking about, @Shamebot

I still cant figure out mine lol.

What about it can't you figure out? If you can manage to get the line #, and the file that its in, then you've "read the stack-trace". After that, its a matter of finding out what exactly is going wrong (which the Exception can help you decipher)

Great information. This will be really helpfull to me so thanks very much for taking the time to do it.

Anybody who likes to code should be grateful for stack traces. They are a tool, not a curse. Vanilla segmentation faults are just no fun to work with at all.