Local debugging guide — Java

Last updated on April 8, 2026

This guide covers everything specific to debugging an Extend Service Extension app written in Java. For general debugging concepts — environment setup, VS Code debug workflow, log reading, and common issues — see:

Project structure​

src/
└── main/
    ├── java/
    │   └── com/accelbyte/extend/serviceextension/
    │       ├── Application.java            # Entry point
    │       ├── service/
    │       │   └── MyService.java          # Your business logic
    │       ├── interceptor/
    │       │   └── AuthServerInterceptor.java  # IAM token and permission validation
    │       └── ...
    └── proto/
        └── service.proto                   # gRPC API definition
FileWhat it does
Application.javaEntry point — wires gRPC server, gRPC-Gateway, metrics, and auth.
service/MyService.javaYour business logic — implements the gRPC service methods.
interceptor/AuthServerInterceptor.javaValidates every incoming request's IAM token and permission.
proto/service.protoDefines the gRPC API — endpoints, request/response shapes, and required permissions.

Port numbers:

PortPurpose
6565gRPC server (internal — used by gRPC-Gateway)
8000gRPC-Gateway HTTP/REST — call this from a browser, Postman, or curl
8080Prometheus metrics endpoint (/metrics)

Running the service locally​

From the terminal​

# Export all variables from your .env file
export $(grep -v '^#' .env | xargs)

./gradlew bootRun

From VS Code​

Use Terminal → Run Task → "Run: Service". This task is defined in .vscode/tasks.json and loads the .env file for you automatically.

Confirming the service is up​

You should see logs like:

{"time":"...","level":"INFO","msg":"app server started","service":"extend-app-service-extension"}
{"time":"...","level":"INFO","msg":"starting gRPC-Gateway HTTP server","port":8000}
{"time":"...","level":"INFO","msg":"serving prometheus metrics","port":8080,"endpoint":"/metrics"}

Open http://localhost:8000<BASE_PATH>/apidocs/ in your browser to verify Swagger UI is live.

Attaching the debugger​

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.serviceextension.Application",
  "envFile": "${workspaceFolder}/.env",
  "cwd": "${workspaceFolder}"
}

Follow the attaching the debugger steps in the generic guide, then select "Debug: Service" from the dropdown.

Other IDEs — JVM remote debug​

Start the app with the JVM debug agent, which listens on port 5005 by default:

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

Then open your IDE (IntelliJ IDEA, Eclipse) and create a Remote JVM Debug configuration targeting localhost:5005.

Where to put breakpoints​

What you want to investigateFile and location
A specific REST endpoint being calledservice/MyService.java — top of the relevant method
Auth/token validation failureinterceptor/AuthServerInterceptor.java — the interceptCall method
Data not saving or loading correctlyThe repository or storage class used in your service
Service not starting at allApplication.java — the main method and bean initialization

For conditional breakpoint syntax, see the Java language guide.

Reading logs​

For jq log filtering, see the Java language guide.

Testing endpoints manually​

For curl and grpcurl usage, see Testing with grpcurl in the generic guide.

For Swagger UI testing (SE-specific), see Testing endpoints manually in the SE main guide.

Java-specific troubleshooting​

Proto changes have no effect​

Symptom: You edited src/main/proto/service.proto but nothing changed at runtime.

Cause: The generated gRPC stubs have not been rebuilt.

Fix: Run a clean build to trigger the protobuf Gradle plugin:

./gradlew clean build

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​

See JVM port conflict for remote debugging in the Java language guide.

Checking for port conflicts (service ports)​

See Checking for port conflicts in the Java language guide.

AI assistance​

The app template ships with a Claude agent skill at .claude/skills/debugging-guide/SKILL.md.

For AI prompting tips and MCP server details, see Debugging with AI assistance in the generic guide.

References​

Last updated on
On this page