Examine suspended program | IntelliJ IDEA Documentation

Examine frames

The state of the program is represented by frames. When the program is suspended, the current frame stack is displayed on the Frames tab of the Debug tool window.

A frame corresponds to the active method or function call. It stores the local variables of the called method or function, its arguments, and the code context that enables expression evaluation.

Frames and threads are selected in the Frames tab

To better understand the concept of frames, let's look into what happens when a program is run. The execution of the program starts from the main method, which in turn calls other methods. Each of these methods may do more method calls. The set of local variables and parameters for each method call is represented by a frame. Each time a method is called, a new frame is added to the top of the stack. When the execution of a method is complete, the corresponding frame is removed from the stack (in the last in, first out fashion).

Examining frames helps you understand why particular parameters were passed to a method and what the state of the caller was at the time of calling.

Thread Statuses

Thread statuses are provided by Java to reflect what is currently happening to the thread in the program.

Thread status	Description
MONITOR	The thread is waiting on a Java monitor.
NOT_STARTED	The thread has not yet been started.
RUNNING	The thread is active and running.
SLEEPING	The thread is sleeping because `Thread.sleep()` or `JVM_Sleep()` was called.
UNKNOWN	The thread status is unknown.
WAIT	The thread is waiting after `Object.wait()` or `JVM_MonitorWait()` was called.
ZOMBIE	The thread has completed execution.

Thread Icons

Icons near each thread indicate the status of the thread relative to the current debugging session.

Icon	Description
	The current thread in suspended state.
	An active thread.
	The thread that has hit the current breakpoint.
	A suspended thread. Threads are marked as suspended when they were paused by the debugger.
	A frozen thread. Threads are marked as frozen when they were manually paused.

Hide frames from libraries

If your program uses external libraries, and you want to omit calls made in library classes, click the Hide Frames from Libraries button located in the top-right part of the Frames tab.

Copy stack to clipboard

To copy the call stack for the current thread, right-click anywhere on the Frames tab and select Copy Stack.

Export threads

If you need to get a report containing the state of each thread and its stack trace, use the Export Threads option. This is useful when you need to share the information about the threads in text format.

Right-click anywhere on the Frames tab and select Export Threads from the menu.
To save a report as a text file, specify the path to the file in the Export Threads dialog and click Save, or click Copy to copy it to the clipboard.

Examine/update variables

The Variables tab shows the list of the variables in the selected frame/thread. The examination of variables is instrumental to understanding why the program operates in a certain way.

The Variables tab shows you the variables visible from the current execution point

The icon on the left of each variable indicates its type.

Variable types

Icon	Description
	Static members of the enclosing class
	Fields of an object (both static and nonstatic)
	Fields containing a self-referencing object (for example, `cause` in `Throwable` before the field gets initialized)
	Final fields
	Static fields
	A thrown exception (only displayed when an exception breakpoint was hit)
	A method return value (only displayed when the Show Method Return Values option is enabled)
	Method parameters
	Enum constants
	Local arrays
	Local primitive types
	Watches and auto-variables.
	Local reference variables

Pin fields

If an object has numerous fields, you can pin some of them, so that they are always displayed at the top of the list. The same priority will apply to other instances of this class.

In the Variables tab, click the icon that indicates the variable type.

When a field is pinned, a blue flag replaces the original icon. To unpin the field, click this flag.

Copy variables

When examining variables, you may need to copy a variable name or value to paste it somewhere else or to compare it with another variable.

To copy the value that a variable holds, right-click the variable and select Copy Value Ctrl+C. For types other than String, the toString representation is copied.
To copy the name of a variable, right-click the variable and select Copy Name.

Compare variables with clipboard

When you need to compare a variable value with some other value, use the Compare Value with Clipboard option. This is helpful, for example, when a variable holds a long string, and you need to compare it with another long string.

Copy the content you are going to compare (for example, from a text file).
In the Variables tab, right-click the variable which you are going to compare with and select Compare Value with Clipboard.
Examine the differences in the Diff Viewer that opens. For additional information on how to efficiently use the Diff Viewer, refer to the Comparing Files and Folders topic.

View variables in a dedicated dialog

IntelliJ IDEA allows you to inspect variables in a dedicated dialog. This is useful when you need to keep track of some variable (or the object whose reference it holds) and at the same time be able to navigate between frames and threads.

Right-click a variable on the Variables tab and select Inspect.

View variables as arrays

In the Variables tab of the Debug tool window, select an array or a DataFrame.
Click a link View as Array/View as DataFrame to the right.
Alternatively, you can choose View as Array or View as DataFrame from the context menu.
The Data View tool window appears.

Set variable values

If there is a need to test how the program would behave in certain conditions or fix its current behavior at runtime, you can do that by setting/changing the variable values.

Right-click a variable on the Variables tab and select Set Value, or select the variable and press F2.
Enter the value for the variable and press Enter.

Navigate to source code

If you need to look into the source code where some variable or class is declared, you can move there right from the Variables tab.

To navigate to the code where the variable is declared, right-click a variable and select Jump to Source F4.
To navigate to the class declaration of the variable type, right-click a variable and select Jump to Type Source F4.
To navigate to a method body from a stack trace element, click Navigate near the stack trace element on the Variables tab.

Examine object references

IntelliJ IDEA provides you with the information on the currently existing objects, which hold a reference to the objects on the Variables tab. The feature also detects indirect references, like those in anonymous classes using outside variables.

To view the list of referring objects, right-click a variable on the Variables tab and select Show Referring Objects.

The Referring Objects dialog opens, allowing you to inspect the references to the selected object and to the referring objects themselves.

When you need the summary on all existing objects of some type, you can get it using the Memory tab of the Debug tool window.

Also, you can configure how different types are displayed. For example, you can use the 'toString' representation or create a custom renderer.

Evaluate expressions

IntelliJ IDEA lets you evaluate expressions during a debugging session to obtain additional details about the program state or test various scenarios at runtime.

Evaluate a simple expression in the editor

The simplest way to evaluate an expression is to point at it in the code. Although this is the quickest way, it cannot be used for evaluating method calls. This is done for safety as they may produce side effects.

Use this option when you need to quickly evaluate an expression from the editor.

Point at the expression which you are going to evaluate. The result of the expression appears in a tooltip.
If you need to view child elements of the resulting object, click or press Ctrl+F1.

If you find value tooltips distracting, you can increase the delay or disable them altogether. To do this, in the Settings/Preferences dialog (Ctrl+Alt+S), go to Build, Execution, Deployment | Debugger | Data Views and set the Show value tooltip and Value tooltip delay options as required.

Evaluate a complex expression in the editor

If you want to evaluate an expression in the code that involves a method call, or you want to be specific about which portion of expression to evaluate, use the Quick Evaluate Expression option.

This option is available only if the program was suspended after hitting a breakpoint (not paused manually).

Place the caret at the expression (to evaluate the closest matching expression) or select a portion of it (if you want to be specific about which part of a complex expression to evaluate).
Click Run | Debugging Actions | Quick Evaluate Expression Ctrl+Alt+F8. Alternatively, hold Alt and click the selection.

You can configure Quick Evaluate to work for a piece of code on just selecting it (without using the menu/shortcut). Use this option carefully, as you can accidentally call methods when it is enabled.

To configure Quick Evaluate on code selection, go to Settings/Preferences | Build, Execution, Deployment | Debugger | Data Views and set the Show value tooltip on code selection option as preferred.

Evaluate arbitrary expressions

Evaluating arbitrary expressions is the most flexible evaluating option. It lets you evaluate any code as long as it is in the context of the current frame. Using it, you can evaluate declarations, method calls, loops, switch expressions, anonymous classes, lambdas, and so on.

Use this feature to get additional information about the current state of the program and test various scenarios all within the same debugging session. This saves a lot of time by reducing the number of sessions you have to run.

This option is available only if the program was suspended after hitting a breakpoint (not paused manually).

If you want to start with some expression or a variable, which is currently in front of you (for example, in the editor or on the Variables tab), select it.
Click Run | Debugging Actions | Evaluate Expression Alt+F8. The shortcut may not work on Ubuntu (for correct operation, adjust the shortcut configuration).
In the Evaluate dialog, modify the selected expression or enter a new one in the Expression field. If you are going to evaluate a code fragment, click Expand Shift+Enter.
Keep in mind that any variables declared in the body of the expression go out of scope after the expression has been evaluated.
Click Evaluate (Ctrl+Enter for multiline mode). The expression result appears in the Result field.
The result of the expression is taken from the return statement. When there is no return statement, the result is taken from the last line of code (it does not even have to be an expression: a literal works too). When there is no valid line to take value from, the result is undefined. If the specified expression cannot be evaluated, the Result field indicates the reason.

The Evaluate dialog is non-modal, so you can switch the focus back to the editor to copy other variables and expressions. You can also open multiple Evaluate dialogs if necessary.

View values inline

IntelliJ IDEA facilitates the debugging process by showing you the values of the variables right next to their usage.

Variable values are displayed at the lines where they are used

Once the variable value has changed, the inline view is updated with the new value and changes its color.

Inline values of the variables change with each step

If a line contains a reference to an object, you can examine its fields right in the editor. From this popup, you can also change the variable values and add inline watches.

Inline values view is enabled by default. To turn it off, in the Settings/Preferences dialog (Ctrl+Alt+S), go to Build, Execution, Deployment | Debugger | Data Views and disable the Show values inline option.

Add an Inline Watch

If you want the result of some expression to appear on a particular line, you can set up an inline watch for that. Inline watches are persistent and remain active after session restart.

Click the inline hint referring to the object whose field you want to track.
In the popup, select the field and click Add as Inline Watch.
Fine-tune the watch if needed. You can use any valid Java expression as a watch.

Inline watches you set in the editor are also shown under Inline Watches in the Variables tab of the Debug tool window.

To remove an inline watch, hover over the watch and click the cross near it.

DFA-assisted debugging

IntelliJ IDEA also provides hints on what is going to happen later in the executed piece of code. This analysis includes exceptions and boolean expression results:

A hint showing the result of a future boolean condition

A hint showing that an exception will be thrown

To disable the analysis of further execution, go to Build, Execution, Deployment | Debugger | Data Views | Java and clear the Predict condition values and exceptions based on data flow analysis checkbox.

Watches

If you want to keep track of some variable or the result of a more complex expression, set up a watch for this variable or expression. This is useful when you need to add something that is not regularly displayed on the list of variables .

This option is available only if the program was suspended after hitting a breakpoint (not paused manually).

Watches are evaluated in the context of the selected frame. Watches cannot be evaluated when they are out of context or when they fail to compile. If this is the case, the watch is marked with the error icon .

By default, the Watches tab is hidden and watches are shown on the Variables tab. To hide/reveal the Watches tab, use the Show watches in variables tab button on the Variables or Watches tab.

Add a watch

For a regular watch that is evaluated everywhere, click New Watch on the Variables tab.
If you only want the watch to be shown when an object of a particular type is inspected, right-click such object in the Variables tab and select New Class Level Watch.
Enter the variable or expression to be evaluated. In expressions, you can evaluate method calls, lambdas declare variables, and so on, as long as this is in the local context.

After you have added a variable/expression to Watches, it stays there and is evaluated for each step, providing you with the result in the current context.

Edit a watch

Right-click the desired watch and select Edit.

Copy a watch

Select the watch you are going to copy.
Click Duplicate Watch on the Variables/ Watches tab or press Ctrl+D.

Change the order of watches

For convenience, you can change the order in which the watches appear on the Variables/ Watches tab.

Use the Move Watch Up/Move Watch Down buttons on the Variables/ Watches tab or Ctrl+Up and Ctrl+Down keyboard shortcuts.

Delete a watch

To remove a single watch, right-click it and select Remove Watch Delete on the Variables/ Watches tab.
To remove all watches, right-click anywhere on the Variables/ Watches tab and select Remove All Watches.

Watches allow for the same actions as variables do. For example, you can view them in a dedicated dialog or use them to navigate to the source code.

Watches are a part of your project. This means you can stop and rerun the debugging session without risk of losing them.

Labels

During debugging, it is sometimes useful to mark some instance so that it is easily identifiable in any context. For this, you can add labels. Once attached, a label accompanies the object for its entire lifetime.

This is especially helpful where conditions or expressions are used – you can refer to that object by label instead of searching for the reference to this object.

Using a labeled object in comparison (Evaluate dialog)

If you want to keep track of an instance regardless of the context, create a watch for this label. With this type of watch, the object is always at hand irrespective of the current frame and thread.

Add label

On the Variables tab, right-click a variable or a watch which is currently referring to the object you want to track. From the menu, select Mark Object F11.
Enter the name for the label. Optionally you can select the display color. For this, click and select the color. After you have finished with configuration, click OK.

Remove label

Right-click the label that you want to remove and select Unmark Object F11 from the menu.

Return to the current execution point

Examining the program state involves navigating in code, and you often need to return to the place where your program is suspended.

Do one of the following:

From the main menu, select Run | Debugging Actions | Show Execution Point.
Press Alt+F10.
Click on the stepping toolbar of the Debug tool window.

The current execution point is indicated with a blue line. The code at this line has not been executed yet.

Blue line indicating the current execution point