Local debugging — Java
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. -
AccelByte credentials —
AB_BASE_URL,AB_CLIENT_ID,AB_CLIENT_SECRET. See Environment setup in the main guide.
JVM remote debug
The Java templates do not ship with a .vscode/ folder. To 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. Attach your IDE's remote JVM debugger to
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.