Remote Debugging

DevDocker includes full debugging support via JDWP (Java Debug Wire Protocol). This lets you set breakpoints, inspect variables, and step through code while GeoServer is running.

Setting up debugging in VSCode/Kiro

1. Create debug configuration:

Create .vscode/launch.json in your workspace:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Debug GeoServer",
      "request": "attach",
      "hostName": "localhost",
      "port": 5005
    }
  ]
}

2. Enable Hot Code Replace (do this before you start debugging):

Add to .vscode/settings.json in the workspace:

{
  "java.autobuild.enabled": true,
  "java.debug.settings.hotCodeReplace": "auto"
}

Without java.autobuild.enabled, Hot Code Replace fails with “Cannot find any changed classes for hot replace!” — the debugger has no way to detect what changed. This setting is required, not optional.

3. Start GeoServer (if not already running):

# start-geoserver.sh

4. Attach debugger:

• Press F5 or click Run → Start Debugging
• You should see “Debugger attached” in the debug console

5. Set a breakpoint:

• Open a Java file (e.g., src/main/src/main/java/org/geoserver/GeoServerApplication.java)
• Click in the left margin next to a line number to set a breakpoint (red dot appears)

6. Trigger the breakpoint:

• Access GeoServer in your browser (http://localhost:8080/geoserver)
• When code execution hits your breakpoint, the debugger pauses
• You can inspect variables, step through code, and evaluate expressions

Hot Code Replacement

For simple method body changes, you can modify code while debugging and — with the settings above — the changes take effect immediately without restarting GeoServer. For structural changes (new methods, fields, classes), you’ll need to rebuild and restart.

Good to know before you rely on it:

• If the edited file isn’t part of an imported project in your workspace, VS Code can’t compile or hot-swap it — you’ll see “is a non-project file” in the Problems panel. Import the module, or rebuild and restart instead.
• GeoServer’s admin UI (Apache Wicket) is stateful: reloading the same page within one browser session redisplays the existing page instance rather than rebuilding it, so a breakpoint that only fires on page construction won’t trigger again. Use an incognito window, clear cookies, or navigate away and back to force a fresh instance.
• After restarting GeoServer, you’ll always need to reattach the debugger (F5) — the JDWP connection doesn’t survive a JVM restart even though your breakpoints stay defined.