Local debugging — Java

Last updated on April 8, 2026

This guide covers everything specific to debugging an Extend app written in Java. For concepts that apply to all Extend apps and languages — environment variables, VS Code debug workflow, log reading, and common issues — see the Extend local debugging guide.

Prerequisites​

  • Java 17 or later — verify with:

    java --version
    # Expected: openjdk 17.x.x ... or later

  • VS Code Extension Pack for Java (vscjava.vscode-java-pack) — install from the VS Code marketplace or accept the recommended extensions prompt when you open the repository.

  • AccelByte credentials — AB_BASE_URL, AB_CLIENT_ID, AB_CLIENT_SECRET. See Environment setup in the main guide.

VS Code launch configuration​

The repository ships with a ready-to-use launch configuration in .vscode/launch.json:

{
  "name": "Debug: Service",
  "type": "java",
  "request": "launch",
  "mainClass": "com.accelbyte.extend.<appname>.Application",
  "envFile": "${workspaceFolder}/.env",
  "cwd": "${workspaceFolder}"
}

The exact mainClass is provided by the app template's .vscode/launch.json.

Steps:

  1. Fill in .env (see Environment setup).
  2. Open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D).
  3. Select "Debug: Service" from the dropdown.
  4. Press F5.

Other IDEs — JVM remote debug​

Start the app with the JVM debug agent listening on port 5005:

export $(grep -v '^#' .env | xargs)
./gradlew bootRun --debug-jvm

The process pauses until a debugger connects. Create a Remote JVM Debug configuration in IntelliJ IDEA or Eclipse targeting localhost:5005.

Conditional breakpoint syntax​

Right-click a breakpoint → Edit Breakpoint → enter a Java expression. Example:

request.getUserId().equals("user_001")

The debugger only pauses when the condition is true.

Reading logs with jq​

# Pretty-print everything
./gradlew bootRun 2>&1 | jq '.'

# Show only ERROR lines
./gradlew bootRun 2>&1 | jq 'select(.level == "ERROR")'

For an overview of the log format and log levels, see Reading and understanding logs in the main guide.

Java-specific troubleshooting​

Gradle daemon issues​

If the service behaves inconsistently between runs, stop the Gradle daemon and try again:

./gradlew --stop
./gradlew bootRun

JVM port conflict for remote debugging​

If port 5005 is already in use when running --debug-jvm:

ss -tlnp | grep 5005

Kill the occupying process, or change the debug port in build.gradle:

bootRun {
    jvmArgs = ["-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5006"]
}

Checking for port conflicts (service ports)​

ss -tlnp | grep -E '6565|8000|8080'

Kill any stale process and start again.

References​

Last updated on
On this page