vscode-java-debug: a Java debugger built on the JDT debug server

An extension that sits on top of two other projects

The Debugger for Java extension is described as a lightweight Java Debugger based on Java Debug Server, which itself extends Language Support for Java by Red Hat. That dependency chain explains most of what you need to know before installing it. The requirements are a JDK of version 1.8.0 or later, VS Code of version 1.19.0 or later as stated in the README, and Language Support for Java by Red Hat at version 0.14.0 or later. So the project is not a standalone debugger. It is the adapter that turns the JDT based Java tooling into a VS Code debug session, and it is maintained by Microsoft as part of the vscjava extension publisher group. The audience is Java developers who have chosen VS Code as their editor and want the debug experience there, rather than people looking for a headless debugger.

Installing from the marketplace or the command line

Installation follows the standard extension path. The README describes opening VS Code, pressing F1 or Ctrl + Shift + P to open the command palette, selecting Install Extension, and typing vscode-java-debug. There is also a Quick Open route with Ctrl + P, which takes a command directly.

ext install vscode-java-debug

The manifest records the details that matter for an extension. The package name is vscode-java-debug, the display name is Debugger for Java, the publisher is vscjava, and the version in the repository is 0.60.0. The engines block is stricter than the README's requirement text, asking for VS Code 1.95.0 or later and Node 20 or Node 22 and above. The extension declares itself in the Debuggers and Programming Languages categories, contributes a breakpoint type for the java language, and requests workspace trust on demand with the description that the extension may require your trust on workspace for code execution.

No-config debugging from the terminal

The feature that distinguishes this extension is that you can debug a Java application without writing a launch.json file. The README gives the command shape: open a terminal in VS Code and use the debugjava command, and the debugger attaches automatically.

# Debug a main class
debugjava -cp bin com.example.Main

# Debug a JAR file
debugjava -jar target/myapp.jar

# Debug with arguments
debugjava -cp bin com.example.Main arg1 arg2

The three forms cover the three things you actually need at a terminal, a classpath with a main class, a packaged jar, and arguments. What makes this work is a terminal integration wrapper, and the README explains how the Java executable is located: it uses JAVA_HOME, then VSCODE_JAVA_EXEC when available, then java on the PATH. Preparing the terminal integration does not start or wait for the Java language extension, and if Java support activates later you have to recreate an existing terminal for it to pick up the newly discovered executable. No-config debug is enabled by default and can be turned off by setting java.debug.settings.enableNoConfigDebug to false, reloading VS Code and recreating existing terminals, which also disables the AI debug_java_application tool while leaving standard F5 and Run and Debug CodeLens behaviour in place.

Copilot integration as a language model tool

The extension now exposes a Language Model Tool so that GitHub Copilot Chat can start a debug session from a natural language request. The README gives the example prompts, such as asking to debug a Spring Boot application, to debug the Main class in the project, or to debug a Calculator with arguments 10 and 5. The AI then detects the project type, whether Maven, Gradle or plain VS Code, builds and compiles the project, and starts debugging with an appropriate configuration. The activation events in the manifest include onLanguageModelTool:debug_java_application, which is how VS Code knows to wake the extension for that tool. The bundled directory in the repository holds the pieces, with the agent documentation under bundled/agents/README.md and the no-config scripts documented under bundled/scripts/noConfigScripts/README.md. The aiKey field in the manifest and the workspace trust request are the two places where the extension asks for permission to do code execution.

The launch options are where the real configuration lives

The Options section of the README is effectively the reference for the launch configuration, and it is long enough to be worth skimming before you set anything up. The mainClass option accepts a fully qualified class name, the special ${file} value for the current Java file, a module and class combination such as com.java9.mymodule/com.mypackage.Main, or a path to the source file, and if you leave it out the debugger resolves the main class from the current project. classPaths and modulePaths both default to automatic resolution from the project, accept the $Auto, $Runtime and $Test scope values, and support exclusion with a leading ! and appending with a path, and multiple values are merged. The projectName option exists because class names can be duplicated across projects, and the README notes it is required when the workspace has multiple Java projects, otherwise expression evaluation and conditional breakpoints may not work. There are also args, sourcePaths, encoding, vmArgs, cwd, env, envFile, stopOnEntry, console and shortenCommandLine.

Where the extension is the wrong choice

The limits are mostly about overlap. The Red Hat Language Support for Java extension has its own debugger, and this extension extends that same stack, so a team that has already standardised on the Red Hat debugging experience has two debuggers for the same project and has to decide which one owns F5. The README itself defers to the other extension's documentation when you have trouble setting up your project, which is an admission that the project setup part of the story lives elsewhere. The second limit is the release cadence and the shape of the codebase. The repository mixes a TypeScript extension layer with a bundled server jar, the manifest points at a specific plugin jar, and the release numbering moves in small increments, 0.58.5, 0.59.0, 0.60.0, with 0.60.0 published on 2026-10-15 and the last push on 2026-10-20. The extension also predates the current VS Code extension host requirements in places, with a webpack build and a tslint configuration at the root alongside a package-lock rather than a modern workspace layout, so it is a codebase in transition. The alternative worth naming is simply using the Red Hat extension's own debugger, which is the same underlying server without a second adapter in the middle.

The repository layout and its own documentation

The top level entries show a mature extension with more than just source. There is bundled/ for the server jar and the agent and script assets, src/ for the TypeScript extension code, resources/ and images/ for assets, test/ for the test suite, and scripts/ for build helpers. Alongside the README there is a Configuration.md, a Troubleshooting.md and a separate Troubleshooting_encoding.md, which tells you the project maintains documentation for the common failure modes separately from the source, and a CHANGELOG.md, a CONTRIBUTING.md and a SECURITY.md. There are localisation files for the extension strings, with package.nls.json as the base and Spanish, Italian, Simplified Chinese and Traditional Chinese variants, and a ThirdPartyNotices.txt for the bundled third party code. The build runs through GitHub Actions with a build.yml workflow, and the repository also carries an .azure-pipelines/ directory, which is the older Microsoft CI path still in place alongside it.

Editorial conclusion

Adopt vscode-java-debug if you want Java debugging in VS Code with launch and attach, a terminal path that needs no launch.json, and Copilot help for building a debug session. Do not adopt it if your team has standardised on the Red Hat Java extension's own debugger, since the two overlap and the README asks you to check that extension's documentation for project setup problems. Verify first that the Language Support for Java extension is installed, since this one extends it, and that your JDK is 1.8.0 or newer and your VS Code meets the version the manifest requires.

Frequently asked questions

Official sources

1. Issues
2. microsoft/vscode-java-debug on GitHub
3. README
4. Releases