Debugging Java in a DevContainer

You need to set breakpoints in a Java service that runs inside a devcontainer. This page attaches the VS Code Java debugger to the in-container JVM — launching directly, or attaching over JDWP for a running service — so debugging works against the real container runtime.

Prerequisites

You need a Java devcontainer with the debugger extension.

  • A Java devcontainer with a pinned JDK.
  • The Java extension pack (includes the debugger) in the container.
  • A JDWP port if attaching to a running service.

Java debug prerequisitesYou need the debugger extension, a launch/attach config, and JDWP for services.Java packdebugger in containerLaunch/attachconfigJDWPfor servicesBreakpointsbind

Step-by-Step Implementation

  1. Ensure the Java pack is installed in the container.
{ "customizations": { "vscode": { "extensions": ["vscjava.vscode-java-pack"] } }, "remoteUser": "vscode" }

  1. Launch the app under the debugger (simple case) — the extension provides a launch config.

  2. Or start a service with JDWP and attach.

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar
  1. Attach the editor to the JDWP port and set breakpoints.
{ "type": "java", "request": "attach", "hostName": "localhost", "port": 5005 }

Java debug modelThe debugger runs in the container and attaches to the in-container JVM, directly or via JDWP.Debugger in containerruns on the serverLaunch configdirect debugJDWP attachfor running servicesBreakpointsbind to real JVM

Common Pitfalls

Java debug issues are a host-run debugger or a missing JDWP port.

Java debug triageA triage path from a non-binding debugger to a working in-container attach.Is the debugger in the container?NOInstall the Java pack in the containerDebugging a running service?YESStart it with JDWP and attachBreakpoints bind

SymptomRoot CauseRemediation
Breakpoints don't bindDebugger not in the containerInstall the Java pack in the container
Can't attach to a serviceNo JDWP agentStart the JVM with the JDWP agent
Attach refusedJDWP port not forwardedForward the JDWP port to the host
Wrong source mappingBuild output staleRebuild so class files match sources

Conclusion

Debug Java where it runs: install the Java debugger into the container and either launch under it or attach over JDWP to a running service. Breakpoints then bind against the real in-container JVM, so what you debug is what actually executes.

Launch vs attachLaunch directly for simple runs; attach over JDWP for running services.Launch modeDirect debugFast for a main()No extra flagsAttach modeJDWP agentRunning servicesForwarded port

FAQ

Why won't my Java breakpoints bind? Usually because the debugger is running on the host rather than in the container. Install the Java extension pack into the container (via customizations.vscode.extensions) so the debugger runs on the server against the in-container JVM, and breakpoints bind to the real runtime.

How do I debug a long-running service in the container? Start the JVM with the JDWP agent (-agentlib:jdwp=...,address=*:5005), forward that port, and use an attach launch configuration pointing at it. The editor then attaches to the live service and you can set breakpoints without restarting it under the debugger.

Do I need to forward the JDWP port? If you attach from the host editor to a container JVM, yes — forward the JDWP port (e.g. 5005) so the debugger can reach it. When the whole debug session runs in-container via the server, the port stays internal and no forwarding is needed.