Running the Debugger in Eclipse

When I started as a Java Developer, I rarely made use of the debugger in Eclipse.  I had vague memories of using a debugger in my undergrad in a class on the Pascal programming language back in the 90’s.  I can’t tell you about the debugger I used, and I can’t even tell you if I used an IDE for that class.  But ever since then I had always been using output statements (“sysouts”) to track program progress and to output the state of variables at each sysout.  Because the complexity level of the code I worked on was fairly moderate, I was able to get by on using this technique alone.

But very soon after working with other Java Devs I was introduced to using the debugger in Eclipse.  I learned how to use the debugger slowly, step by step, until I had become competent in using it.  However, I also learned that setting up “breakpoints” in code, stepping through the code and drilling down into deeply nested object values was not always as fast as just throwing into the code a sysout with all the variable values I needed in one quick spot.

So with that caveat, let me explain how to use the debugger in Eclipse.  It truly enhances your ability to track what is going on in your code.  I will assume here that you don’t know anything about the debugger.  I will also start with using the debugger for Java, for a Java Application (not yet for using it with a web server).

>> “Find the Debugger”




To find the debugger, there are several locations in Eclipse that will take you there.  The first is the “Run” menu.  It is great because it allows you to Run or Debug programs, control “breakpoints”, “watch” and “inspect” variables as you step through a program, and more.  Notice below that the keyboard shortcuts are listed alongside the menu options.  This comes in handy when “stepping” through the code line-by-line, discussed here later on.  Also notice that some of the images shown below to the left of the menu item also appear on the main toolbar, including “Resume” (aka start, F8), “Terminate” (aka stop), “Step Into” (F5) and “Step Over” (F6).  Remember this for the “breakpoints” section below.




Second, there is the “debug” button on the toolbar menu.  This button has a green beetle-like “bug” as its icon (a little hard to see), with a downward pointing triangle next to it, indicating that you can click on the arrow to see additional options.  If you click the “bug” button, it will run that current open file in “debug” mode right away.  So be careful not to push that button if you meant to click the down triangle.




Third, there is a right-click menu that gets you to run the current open file in “debug” mode.  Right-click the currently open class (it should have a properly set up main method in it in order to be run), and select “Debug As” (this is right next to the “Run As” option).  You are given the option of running the program as a “Java Application” or to select “Debug Configurations”.  The first option simply runs the class in debug mode.  The second option opens up a wizard to allow you to fine-tune how you want to debug programs.




Deciding which location to activate or modify the debugger depends on how much control you need.  I suggest using the “Run” menu option if you want control but you don’t want to open a wizard and if you like the one-click speed of a menu.  Honestly though, I think usually you will accept most of the default options for the debugger and you will simply click the debug button or use the right-click method to run your program in debug mode.  Lastly, if you need to change how the debugger works, using the button or right-click method to configure the wizard is always there for you (but I believe its the least likely that you will use).

>> “Breakpoints”

Breakpoints are the heart of the debugger.  Without breakpoints, running your code in debug mode is no different than running your code via “Run As”.  A “breakpoint” is a spot that you designate as a kind of pause or stopping point for your program to reach and then, once reached, halts progress, waiting for your next command.  You then have the option to start up the program again from its last position, running until the program is completed or until it reaches another breakpoint.  Along the way, when the program progress is halted at a breakpoint, Eclipse allows you to check the values of all the variables available to the program at the location of the breakpoint.  This is the main purpose of using breakpoints: if your program is not behaving as expected, the value of certain variables at the breakpoints that you have set up should help you to ascertain the bad behavior.  If you are still in the dark, then you should either rerun the program with the same breakpoints to watch more closely what is going on, or add/remove/alter your breakpoints to get different results.  One more vital feature of breakpoints is that you have the ability to “step” through the code after a breakpoint, one line at a time, to view the program variables and how they change line-by-line as the code progresses.  Placing breakpoints at the beginning of a method, and then stepping through the method line-by-line is a typical approach that avoids you having to set a breakpoint for every line you want to investigate.




So, first off you pick a spot in your code to set a breakpoint.  This is done simply by locating the thin vertical strip that exists in the Eclipse editor, between the window border on the left and the line numbers on the right.  Double clicking this strip at the line number you choose will place a round blue dot at that point.  This blue dot is the breakpoint.  If you double click the dot, it will be removed.  You have “toggled” the breakpoint on/off.  Toggling a breakpoint off means that it is removed, and running your code in debug mode will ignore removed breakpoints.  Another thing to consider is that each of these blue dots will contain a checkmark icon while the code is running in debug mode, indicating that Eclipse can recognize the breakpoint you placed, and will stop there when the debugger reaches it.  This is important to notice because sometimes Eclipse will have an error during debugging and some breakpoints may not have that checkmark.  When that happens, eclipse skips those breakpoints.  This usually means that you will have to restart running in debug mode, or find some other solution (aka when debugging a web app you may need to restart the server or do a clean projects action) to get the breakpoint to be “checked” during debug mode.  After you have selected all your breakpoints, one or more in each file you wish to track, doing a Debug As command on the class with the main method will start your program in debug mode.




At this point Eclipse will prompt you if you wish to enter “Debug Perspective”.  By clicking yes your Eclipse perspective changes, and you have access to several important views.  In general, unless you have only one breakpoint and you are only checking that the code “enters” the logic you wish to track, you should usually accept the change to Debug Perspective to get access to these views.




On the top-left corner you have the “Debug” view.  This lists the “debug trace” (like a java stack trace) showing the methods calls that led up to reaching the breakpoint.  This tells you how the flow of control got to your breakpoint, and hopefully giving you good information about what you could expect variable data values to be based on this history.  In addition, the methods are surrounded by what is called a “Thread”, which for our purposes is just the process that was halted by the breakpoint.  It is identified in the debug trace as “suspended”, meaning that the breakpoint has halted program execution at this point.


  1. Breakpoints: check/no check, toggle on/off, inner/method signature/conditional/etc
  2. Stepping through code: F5/F6/F8, buttons, stopping/pausing, debug stack trace
  3. Variables/Breakpoints
  4. Run / Debug Configuration Wizard
  5. Internal / External Web Server debugging
  6. Add Diagrams

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s