IntelliJ IDEA 2023.3 Help

Debug code

IntelliJ IDEA provides a debugger for Java code. Depending on the installed/enabled plugins, you can also debug code written in other languages.

During a debugging session, you launch your program with the debugger attached to it. The purpose of the debugger is to interfere with the program execution and provide you with the information on what’s happening under the hood. This facilitates the process of detecting and fixing bugs in your program.

Before debugging

  1. Make sure the Generate debugging info option is turned on (the default setting) in Settings | Build, Execution, Deployment | Compiler | Java Compiler.

    This setting is not absolutely required for debugging, however, we recommend leaving it enabled. Disabling it allows you to save disk space at the cost of some debugger functionality.

  2. Configure common debugging properties and behavior in Settings | Build, Execution, Deployment | Debugger.

    If you are new to debugging, the out-of-the-box configuration will work for you. The topics about each debugger functionality provide references and explain the related settings where applicable. If you are an advanced user and looking for some particular property, see the Debugger reference section.

  3. Define a run/debug configuration if you are going to use a custom one. This is required if you need some arguments to be passed to the program or some special activity to be performed before launch. For more information about setting up run/debug configurations, refer to the Run/debug configurations section. Most of the time, you don't need this to debug a simple program that doesn't expect arguments or have any special requirements.

General debugging procedure

There is no one-size-fits-all procedure for debugging applications. Depending on actual requirements, you may have to use different actions in a different order. This topic provides general guidelines, which represent typical debugging steps. The details on how and when to use particular features are provided in the respective topics.

  1. Define where the program needs to be stopped. This is done using breakpoints. Breakpoints are special markers, which represent places and conditions when the debugger needs to step in and freeze the program state. A program, which has been frozen by the debugger is referred to as suspended.

    The alternative to using breakpoints is manually suspending the program at an arbitrary moment, however this method imposes some limitations on the debugger functionality and doesn't allow for much precision as to when to suspend the program.

  2. Run your program in debug mode.

    Just like with regular running of the program, you can run multiple debugging sessions at the same time.

  3. After the program has been suspended, use the debugger to get the information about the state of the program and how it changes during running.

    The debugger provides you with the information about variable values, the current state of the threads, breakdown of objects that are currently in the heap, and so on. It also allows you to test your program in various conditions by throwing exceptions (for example, to check how they are handled) or running arbitrary code right in the middle of the program execution.

    While these tools let you examine the program state at a particular instant, the stepping feature gives you the control over step-by-step execution of the program. By combining the tools you can deduce where the bug is coming from and test your program for robustness.

  4. When you have determined what needs to be fixed, you can do it without terminating the session. For this purpose, IntelliJ IDEA provides a functionality allowing you to adjust and reload pieces of your code on the fly. This approach is covered in the Reload modified classes topic.

Debugger refreshers

If you are already familiar with IntelliJ IDEA debugger and want to get an overview of various useful features and approaches, take a look at Debugger Refresher video series.

Debugger Essentials covers basic topics like line breakpoints, stepping, controlling the debug session, watches, expression evaluation, and breakpoint conditions.

Debugger Advanced covers breakpoint types and settings, advanced stepping, remote debug, renderers, and more.

Debugger Professional covers advanced topics like using HotSwap, debug labels, asynchronous stack traces, and debugging decompiled code.

Last modified: 15 March 2024