Debugging Java in Visual Studio Code

Visual Studio Code allows you to debug Java applications through the Debugger for Java extension. It's a lightweight Java debugger based on Java Debug Server, which extends the Language Support for Java by Red Hat.

Here's a list of supported debugging features:

  • Launch/Attach
  • Breakpoints
  • Exceptions
  • Pause & Continue
  • Step In/Out/Over
  • Variables
  • Call Stacks
  • Threads
  • Debug Console
  • Evaluation
  • Hot Code Replace

The Java debugger is an open source project, which welcomes contributors to collaborate through GitHub repositories:

Install

For the debugger to work, you also need to have the Language Support for Java(TM) by Red Hat extension installed. To make it easier, there is a Java Extension Pack which bundles the Language Support for Java(TM) by Red Hat, the Debugger for Java and several other popular Java extensions.

You can manually install the extension pack from the Extensions view (⇧⌘X (Windows, Linux Ctrl+Shift+X)) by typing vscode-java-pack in the search box. You will also be prompted to install the Java Extension Pack when you edit a Java file in VS Code for the first time.

Use

It's easy to run and debug your Java application as we provide several entry points for that.

CodeLens

Once the debugger is activated, you will find Run|Debug on the CodeLens of your main() function.

CodeLens

Clicking F5

Once you click F5, the debugger will automatically find the entry point of your project and start debugging.

Resolving Main Class

It's possible that there might be multiple debugging configurations for your project and you can always add and modify those then select the desired one to run.

Java Debugging

If there's no debug configuration file launch.json in your project, the debugger will automatically find the main class and generate the configuration for you to launch your application. VS Code keeps debugging configuration information in a launch.json file located in a .vscode folder in your workspace (project root folder) or in your user settings or workspace settings. For more details, please read Launch configurations

There's also a convenient setting for debugging current file so the editor knows which file is currently active and choose it as the entry point.

Java Debugging

Debugging single files

VS Code can run and debug single Java files without any project.

Debug Single File

Debugging external files

The Java debugger also supports external source files. This lets you debug third party classes when they are inside a JAR or a source attachment. Set your breakpoints in those classes before you start debugging. You can also attach missing source code with a zip/jar file using the Context menu Attach Source action.

Debug Single File

Java 9 is supported with VS Code Java Debugger as well.

Java 9 Support

Debug session inputs

The default Debug Console in VS Code doesn't support inputs. If your program need inputs from a terminal, you can use the Integrated Terminal (⌃` (Windows, Linux Ctrl+`)) within VS Code or an external terminal to launch it.

Launch in Terminal

Step filtering

Step filter is supported by the extension to filter out types that you do not wish to see or step through while debugging. With this feature, you can configure the packages to filter within your launch.json so they could be skipped when you step through.

Step Filter

Expression evaluation

The debugger also lets you evaluate expressions in the WATCH window as well as the Debug Console. You can also use this feature for conditional breakpoint setting.

Expression Evaluation

Conditional breakpoint

With the help of expression evaluation, the debugger also supports conditional breakpoint. You can set your breakpoint to break when expression evaluates to true.

Conditional Breakpoint

Hot Code replacement

Another advanced feature the debugger supports is 'Hot Code' replacement. Hot code replacement (HCR) is a debugging technique whereby the Java debugger transmits new class files over the debugging channel to another Java Virtual Machine (JVM). HCR facilitates experimental development and fosters iterative trial-and-error coding. With this new feature, you can start a debugging session and change a Java file in your development environment, and the debugger will replace the code in the running JVM. No restart is required, which is why it’s called "hot". Below is an illustration of how you can use HCR with Debugger for Java in VS Code.

Hot Code Replacement

Logpoints

Logpoints is also supported by Java Debugger. Logpoints allow you to send output to debug console without editing code. They’re different from breakpoints because they don’t stop the execution flow of your application.

Hot Code Replacement

Configuration

There are many options and settings available to configure the debugger. For example, configuring the current working directory (cwd) and environment variables is easily done with launch options.

Configure Variables

Consult the documentation for the Language Support for Java by Red Hat extension for help with setting up your project.

Below are all the configurations available for Launch and Attach, for more information about how to write the launch.json file, refer to Debugging.

Launch

  • mainClass (required) - The fully qualified class name (e.g. [java module name/]com.xyz.MainApp) or the java file path of the program entry.
  • args - The command-line arguments passed to the program. Use "${command:SpecifyProgramArgs}" to prompt for program arguments. It accepts a string or an array of string.
  • sourcePaths - The extra source directories of the program. The debugger looks for source code from project settings by default. This option allows the debugger to look for source code in extra directories.
  • modulePaths - The modulepaths for launching the JVM. If not specified, the debugger will automatically resolve from current project.
  • classPaths - The classpaths for launching the JVM. If not specified, the debugger will automatically resolve from current project.
  • encoding - The file.encoding setting for the JVM. If not specified, 'UTF-8' will be used. Possible values can be found in http://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html.
  • vmArgs - The extra options and system properties for the JVM (for example -Xms<size> -Xmx<size> -D<name>=<value>), it accepts a string or an array of string.
  • projectName - The preferred project in which the debugger searches for classes. There could be duplicated class names in different projects. This setting also works when the debugger looks for the specified main class when launching a program. It is required when the workspace has multiple Java projects, otherwise the expression evaluation and conditional breakpoint may not work.
  • cwd - The working directory of the program. Defaults to ${workspaceFolder}.
  • env - The extra environment variables for the program.
  • stopOnEntry - Automatically pause the program after launching.
  • console - The specified console to launch the program. Defaults to internalConsole.
    • internalConsole - VS Code debug console (input stream not supported).
    • integratedTerminal - VS Code integrated terminal.
    • externalTerminal - External terminal that can be configured in user settings.
  • stepFilters - Skip specified classes or methods when stepping.
    • classNameFilters - Skip the specified classes when stepping. Class names should be fully qualified. Wildcard is supported.
    • skipSynthetics - Skip synthetic methods when stepping.
    • skipStaticInitializers - Skip static initializer methods when stepping.
    • skipConstructors - Skip constructor methods when stepping.

Attach

  • hostName (required) - The host name or IP address of remote debuggee.
  • port (required) - The debug port of remote debuggee.
  • timeout - Time out value before reconnecting, in milliseconds (default to 30000 ms).
  • sourcePaths - The extra source directories of the program. The debugger looks for source code from project settings by default. This option allows the debugger to look for source code in extra directories.
  • projectName - The preferred project in which the debugger searches for classes. There could be duplicated class names in different projects. It is required when the workspace has multiple java projects, otherwise the expression evaluation and conditional breakpoint may not work.
  • stepFilters - Skip specified classes or methods when stepping.
    • classNameFilters - Skip the specified classes when stepping. Class names should be fully qualified. Wildcard is supported.
    • skipSynthetics - Skip synthetic methods when stepping.
    • skipStaticInitializers - Skip static initializer methods when stepping.
    • skipConstructors - Skip constructor methods when stepping.

User Settings

  • java.debug.logLevel: minimum level of debugger logs that are sent to VS Code, defaults to warn.
  • java.debug.settings.showHex: show numbers in hex format in "Variables" viewlet, defaults to false.
  • java.debug.settings.showStaticVariables: show static variables in "Variables" viewlet, defaults to true.
  • java.debug.settings.showQualifiedNames: show fully qualified class names in "Variables" viewlet, defaults to false.
  • java.debug.settings.maxStringLength: the maximum length of string displayed in "Variables" or "Debug Console" viewlet, the string longer than this length will be trimmed, defaults to 0 which means no trim is performed.
  • java.debug.settings.enableHotCodeReplace: enable hot code replace for Java code. Make sure the auto build is not disabled for VSCode Java. See the wiki page for more information about usages and limitations.
  • java.debug.settings.enableRunDebugCodeLens: enable the CodeLens provider for the run and debug buttons over main entry points, defaults to true.
  • java.debug.settings.forceBuildBeforeLaunch: force building the workspace before launching java program, defaults to true.

Troubleshooting

Detailed troubleshooting guide could be found in our GitHub Repository.

Feedback and questions

You can find the full list of issues at Issue Tracker. You can submit a bug or feature suggestion and participate in the community driven Gitter channel.

Next steps

Read on to find out about:

  • Debugging - Find out how to use the debugger in VS Code with your project for any language.

And for Java: