Local Debugging Guide for Extend Override — Java

Last updated on April 10, 2026

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

The examples in this guide use the matchmaking use case (matchmaking-function-grpc-plugin-server-java). The project structure and debugging steps are the same for every other Override use case — only the service file and proto differ. See the service file reference table at the end of this guide.

Project structure​

matchmaking-function-grpc-plugin-server-java/
├── build.gradle                         # Gradle build — includes protobuf plugin
├── gradlew                              # Gradle wrapper
├── .env.template                        # Environment variable template
└── src/main/
    ├── java/net/accelbyte/matchmaking/function/grpc/server/
    │   ├── App.java                     # Entry point — gRPC server, auth, observability
    │   ├── MatchmakingFunctionService.java  # Your override logic
    │   ├── GameRules.java               # Rules parsing (POJO)
    │   ├── AllianceRule.java            # Alliance rule model
    │   ├── config/
    │   │   └── AppConfiguration.java   # Spring Boot configuration
    │   └── interceptor/
    │       ├── AuthInterceptor.java     # IAM token validation interceptor
    │       └── LoggingInterceptor.java  # Request/response logging interceptor
    ├── proto/
    │   └── matchFunction.proto          # Protobuf definition
    └── resources/
        ├── application.yml              # Server config, auth toggle
        └── logback-spring.xml           # Logging configuration
FileWhat it does
App.javaEntry point — starts the gRPC server, wires the auth interceptor and observability stack.
MatchmakingFunctionService.javaYour override logic — extends MatchFunctionGrpc.MatchFunctionImplBase, implements getStatCodes, validateTicket, enrichTicket, makeMatches, backfillMatches.
interceptor/AuthInterceptor.javaValidates every incoming gRPC call's IAM token.
src/main/proto/matchFunction.protoProtobuf definition — source of truth for service methods.
src/main/resources/application.ymlServer configuration, including auth toggle.

Port numbers:

PortPurpose
6565gRPC server — receives calls from AGS
8080Prometheus metrics endpoint (/metrics)
Auth defaults to disabled in Java

In application.yml, PLUGIN_GRPC_SERVER_AUTH_ENABLED defaults to false (${PLUGIN_GRPC_SERVER_AUTH_ENABLED:false}). This is the opposite of the Go, Python, and C# repos, which default to true. Always set it explicitly in your .env to avoid unexpected behavior in either direction.

Running the service locally​

From the terminal​

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

./gradlew bootRun

Confirming the service is up​

You should see Spring Boot and gRPC startup logs similar to:

INFO  net.accelbyte.matchmaking.function.grpc.server.App - Starting App
INFO  o.l.springboot.grpc.GRpcServerRunner - Starting gRPC Server ...
INFO  o.l.springboot.grpc.GRpcServerRunner - gRPC Server started, listening on port 6565
INFO  o.s.b.w.embedded.tomcat.TomcatWebServer - Tomcat started on port(s): 8080

Verify the gRPC server is reachable:

grpcurl -plaintext localhost:6565 list
No VS Code tasks

The Java Override repo does not ship with a .vscode/tasks.json. Use ./gradlew bootRun from the terminal, or configure a VS Code task manually to suit your workflow.

Attaching the debugger​

The Java repo does not ship with a .vscode/launch.json. Use Gradle's built-in JVM debug support instead:

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

This starts the application and suspends it until a debugger connects on port 5005.

Then add this launch configuration to your VS Code .vscode/launch.json (create the file if it does not exist):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach: JVM (5005)",
      "type": "java",
      "request": "attach",
      "hostName": "localhost",
      "port": 5005
    }
  ]
}

Select "Attach: JVM (5005)" from the Run and Debug dropdown to connect.

IntelliJ IDEA / Eclipse​

Create a Remote JVM Debug configuration targeting localhost:5005. Run ./gradlew bootRun --debug-jvm in a terminal, then attach from the IDE.

Where to put breakpoints​

What you want to investigateFile and location
A specific gRPC method being calledMatchmakingFunctionService.java — top of the relevant method
Streaming ticket processingMatchmakingFunctionService.java — inside the makeMatches StreamObserver.onNext
Rules parsingMatchmakingFunctionService.java — gson.fromJson(rules.getJson(), GameRules.class)
Auth / token validation failureinterceptor/AuthInterceptor.java — interceptCall method
Service not starting at allApp.java — the main method and Spring context initialization

For conditional breakpoint syntax, see the Java language guide.

Reading logs​

The service uses Logback with structured log output configured in logback-spring.xml. For jq log filtering, see the Java language guide.

To stream only error-level output while the service runs:

./gradlew bootRun 2>&1 | grep ERROR

Testing the override manually​

For grpcurl usage and triggering the overridden AGS feature, see Testing the override manually in the Override main guide.

The demo/ directory contains a Postman collection (*.postman_collection.json) with pre-built requests. Import it into Postman and update baseUrl and token for your local setup.

Java-specific troubleshooting​

Proto changes have no effect​

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

Cause: The generated gRPC stubs have not been rebuilt.

Fix:

./gradlew generateProto

Or run a full clean build to guarantee regeneration:

./gradlew clean build

PLUGIN_GRPC_SERVER_AUTH_ENABLED defaults to false​

Symptom: Auth appears to be disabled even though you did not explicitly disable it.

Cause: The application.yml default for PLUGIN_GRPC_SERVER_AUTH_ENABLED is false (unlike Go, Python, and C# which default to true).

Fix: Set PLUGIN_GRPC_SERVER_AUTH_ENABLED=true explicitly in your .env if you want auth enabled, or confirm false is correct for your local dev session.

Gradle daemon issues​

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

./gradlew --stop
./gradlew bootRun

JVM port conflict for remote debugging​

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

AI assistance​

Each Override use case's 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 Override main guide.

Service file reference by use case​

The debugging workflow above applies to all Override use cases. Only the service file and proto vary. Use this table to find your implementation file:

Use caseJava service fileProto file
Matchmaking…/grpc/server/MatchmakingFunctionService.javasrc/main/proto/matchFunction.proto
Cloud Save ValidatorSee repo READMESee repo README
Lootbox RollSee repo READMESee repo README
Profanity FilterSee repo READMESee repo README
RevocationSee repo READMESee repo README
Rotating Shop ItemsSee repo READMESee repo README
Session DSMSee repo READMESee repo README
Session ManagerSee repo READMESee repo README
Challenge AssignmentSee repo READMESee repo README

For the repository link for each use case and language, see Extend Override repositories.

References​

Last updated on
On this page