Local Debugging Guide for Extend Override

Last updated on April 10, 2026

Overview​

This guide walks you through debugging an Extend Override app on your local machine.

Common debugging concepts

For debugging concepts shared across all Extend app types — environment variable setup, VS Code debug workflow, log reading, and common startup errors — see the Extend local debugging guide.

Extend Override has nine use cases (matchmaking, cloud-save-validator, lootbox-roll, profanity-filter, revocation, rotating-shop-items, session-dsm, session-manager, challenge-assignment). The debugging workflow — ports, auth, run/attach/test pattern, and proto regeneration — is identical across all use cases. This guide covers all of them. For the service file and proto that are specific to your use case, see the reference table in the language guide for your language.

The guide focuses on Visual Studio Code (VS Code), but the concepts apply to any editor or IDE.

For language-specific setup — prerequisites, project structure, run commands, and debugger configuration — jump straight to your language:

How a call flows through the service​

Every Extend Override app is built on the same layered stack regardless of language or use case. Understanding this helps you narrow down where a problem originates:

AGS service (intercepts operation)
       │  gRPC  (with IAM bearer token)
       ▼
 gRPC Server  (port 6565)   ← your override logic lives here
       │
       ▼
 Returns override result to AGS

Port summary:

PortPurpose
6565gRPC server — receives calls from AGS
8080Prometheus metrics endpoint (/metrics)

When something goes wrong, trace the problem layer by layer:

SymptomMost likely layerWhere to look first
Service won't startEnvironment / credentials.env file, IAM client credentials
Override not triggeredRegistration in Admin PortalExtend configuration, override binding
Auth errors on every callPLUGIN_GRPC_SERVER_AUTH_ENABLEDSet to false in .env for local dev
Override triggered but returns wrong resultBusiness logicOverride method implementation
Debugger never pausesPort conflict or build modeCheck running processes on port 6565
Proto changes ignoredGenerated code staleRegenerate protobuf bindings

Environment setup​

For the common variables (AB_BASE_URL, AB_CLIENT_ID, AB_CLIENT_SECRET, LOG_LEVEL) and how to create and verify your .env file, see Environment setup in the common debugging guide for Extend apps.

Extend Override-specific variable: PLUGIN_GRPC_SERVER_AUTH_ENABLED​

Unlike Extend Event Handler, Extend Override validates IAM bearer tokens on every incoming gRPC call. By default this is enabled:

PLUGIN_GRPC_SERVER_AUTH_ENABLED=true
VariablePurposeRecommended value for local debugging
PLUGIN_GRPC_SERVER_AUTH_ENABLEDEnables IAM token validation on gRPC callsfalse to skip auth during local development

When PLUGIN_GRPC_SERVER_AUTH_ENABLED=true, every call from grpcurl or a test client must include a valid IAM bearer token. Set it to false to simplify local testing unless you are specifically debugging auth behavior.

No BASE_PATH

Extend Override does not use a BASE_PATH variable. There is no gRPC-Gateway and no HTTP/REST layer — AGS calls the gRPC server directly.

Running the service locally​

For VS Code task and terminal run instructions, see Running the service locally in the common debugging guide for Extend apps.

Confirming the gRPC server is up​

Once the service starts, look for logs similar to the following (exact format varies by language):

{"level":"INFO","msg":"gRPC server listening","address":"[::]:6565"}
{"level":"INFO","msg":"prometheus metrics served at :8080/metrics"}

You can also verify that gRPC reflection is working:

grpcurl -plaintext localhost:6565 list

For the exact terminal run command for your language, see the language-specific guide.

Attaching the debugger​

For VS Code debugger attachment steps, see Attaching the debugger in VS Code in the common debugging guide for Extend apps.

For the Override-specific .vscode/launch.json configuration and non-VS Code setups, see the language-specific guide.

Setting breakpoints and inspecting state​

For how to set breakpoints, use the VS Code debug panels, step through code, and write conditional breakpoints, see Setting breakpoints and inspecting state in the common debugging guide for Extend apps.

For the recommended breakpoint locations in your Override service files and language-specific conditional syntax examples, see the language-specific guide.

Reading logs​

For the structured JSON log format, log levels, gRPC call pairs, and jq usage, see Reading and understanding logs in the common debugging guide for Extend apps.

For the language-specific jq pipe command, see the language-specific guide.

Common issues​

For common issues that apply to all Extend apps — credential errors, 401 Unauthenticated, and breakpoints that are never hit — see Common issues in the common debugging guide for Extend apps.

The issues below are specific to Extend Override.

Override not triggered​

Symptom: The gRPC server is running and healthy, but your breakpoints never fire and logs show no incoming calls.

Cause: The override app is not bound to the target AGS feature in the Admin Portal.

Fix:

  1. Go to the Admin Portal.
  2. Navigate to Extend > the relevant use case (for example, Matchmaking).
  3. Verify the app is deployed, active, and bound to the correct namespace.
  4. If testing locally, ensure your AGS environment is configured to route calls to your local service (for example, via a tunnel or local network route).

Auth errors on every call — PLUGIN_GRPC_SERVER_AUTH_ENABLED​

Symptom: Every gRPC call returns unauthenticated or permission denied, even with a valid IAM token.

Cause: The auth interceptor is active and rejecting the token, or the IAM credentials in .env are wrong.

Fix: For local debugging, set PLUGIN_GRPC_SERVER_AUTH_ENABLED=false in your .env to bypass token validation entirely. If you need auth enabled, verify AB_CLIENT_ID, AB_CLIENT_SECRET, and AB_BASE_URL in your .env file.

Proto changes have no effect​

Symptom: You edited the .proto file but the behavior of the service did not change.

Cause: The generated code stubs have not been regenerated.

Fix: Run the "Proto: Generate" VS Code task (where available), or run ./proto.sh directly (Go and Python), or ./gradlew generateProto (Java), or rebuild the project (C#). Then restart the service.

Testing the override manually​

There is no Swagger UI or HTTP endpoint — AGS calls the gRPC server directly.

Trigger the overridden AGS feature​

The most realistic test is to trigger the AGS feature your override is registered for. The exact steps depend on your use case. Each use case's customize guide has use-case-specific invocation steps:

Test the gRPC server directly with grpcurl​

For testing with grpcurl, see Testing with grpcurl in the common debugging guide for Extend apps.

Use gRPC reflection to discover available services:

grpcurl -plaintext localhost:6565 list

Call a specific method (example for matchmaking — adjust the service and method name for your use case):

grpcurl -plaintext \
  -d '{"rules": {"json": "{}"}}' \
  localhost:6565 \
  accelbyte.matchmakingv2.matchfunction.MatchFunction/GetStatCodes

When PLUGIN_GRPC_SERVER_AUTH_ENABLED=true, add -H "Authorization: Bearer <your-token>" to every grpcurl call.

Debugging with AI assistance​

Optional section

If your team does not use AI tooling, or if you are discouraged from using AI at work, skip this section. Every other section in this guide is fully self-contained and does not require an AI assistant.

AI coding assistants such as Claude Code, GitHub Copilot, and others can act as a debugging companion — explaining unfamiliar code, parsing logs, and suggesting targeted fixes.

Using the debugging skill​

Each Extend Override app template repository ships with a ready-made agent skill at .claude/skills/debugging-guide/SKILL.md. A skill is a set of instructions that tells the AI exactly how to help with a specific domain — in this case, debugging Extend Override apps.

The skill file is available in each use case's template repository (see Repositories for the full list). Once the skill is active, invoke it by typing one of the following in your AI chat:

IntentWhat to type
Debug a live issue/debugging-guide Go — getting unauthenticated on every call
Write or update the debugging guide/debugging-guide write Go
Let the AI decideDescribe the problem naturally — the AI picks the right mode
Compatibility

Agent skills work out of the box with Claude Code. For other AI tools or IDE extensions, check whether they support the Agent Skills open standard. If your tool does not support skills, copy the contents of .claude/skills/debugging-guide/SKILL.md and paste it as the first message (or system prompt) in your chat session.

Below is a reference skill file you can adapt and save as .claude/skills/debugging-guide/SKILL.md in your own Extend Override repository.

View the full debugging skill (SKILL.md)
---
name: debugging-guide
description: >
  Expert guide writer and debugging assistant for AccelByte Extend Override apps.
  Use when a developer asks for help debugging their Override service, diagnosing startup or
  runtime errors, understanding logs, setting up a debugger, or when writing or updating a
  DEBUGGING_GUIDE.md for an Extend Override app. Covers Go but the workflow applies to other
  supported languages (Python, C#, Java).
argument-hint: "[language] [brief issue description or 'write guide']"
allowed-tools: Read, Grep, Glob, Bash(go *), Bash(dlv *), Bash(ss *), Bash(grpcurl *), Bash(jq *)
---

# Debugging Guide Skill — Extend Override

You are an expert backend developer and technical writer specializing in AccelByte Gaming
Services (AGS) Extend Override apps. Your two modes of operation are:

1. **Debug Mode** — Help a developer diagnose and fix a real issue in their running service.
2. **Write Mode** — Author or update a `DEBUGGING_GUIDE.md` for an Extend Override repository.

Detect which mode is needed from `$ARGUMENTS`. If the argument mentions a specific error,
log output, or symptom, use Debug Mode. If it mentions "write", "guide", or "document", use
Write Mode. If ambiguous, ask one clarifying question.

---

## Architecture Context

Every Extend Override app shares this architecture:

\`\`\`
AGS service (intercepts operation)
       │  gRPC  (with IAM bearer token)
       ▼
 gRPC Server  (port 6565)   ← your override logic lives here
       │
       ▼
 Returns override result to AGS
\`\`\`

Key environment variables:

| Variable | Purpose |
|---|---|
| `AB_BASE_URL` | AccelByte environment base URL |
| `AB_CLIENT_ID` / `AB_CLIENT_SECRET` | OAuth client credentials |
| `PLUGIN_GRPC_SERVER_AUTH_ENABLED` | `false` to skip IAM token validation locally |
| `LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` |

---

## Debug Mode

### Step 1 — Identify the layer where the failure occurs

- Service fails to **start** → environment variables and IAM login.
- All calls return **unauthenticated** → set `PLUGIN_GRPC_SERVER_AUTH_ENABLED=false` locally.
- Override is **never triggered** → check Admin Portal binding.
- Returns **wrong result** → business logic in the service implementation file.
- Debugger **won't pause** → port conflicts or build mode.
- **Proto changes ignored** → regenerate bindings.

### Step 2 — Collect evidence

1. Ask for full log output at `LOG_LEVEL=debug`. Look for `"level":"ERROR"` lines.
2. Read the source files referenced in the error before suggesting a fix.
3. Check environment: `printenv | grep -E 'AB_|PLUGIN_GRPC|LOG_LEVEL'`
4. Check ports: `ss -tlnp | grep -E '6565|8080'`

### Step 3 — Common-issue checklist

| Symptom | Likely cause | Where to look |
|---|---|---|
| `unable to login using clientId and clientSecret` | Wrong credentials or unreachable `AB_BASE_URL` | Entry point → OAuth login |
| All calls return `unauthenticated` | Auth interceptor active with missing token | Set `PLUGIN_GRPC_SERVER_AUTH_ENABLED=false` |
| Override never fires | App not bound in Admin Portal | Admin Portal Extend configuration |
| Override returns wrong result | Business logic error | Service implementation file |
| Breakpoints never hit | Port conflict or auth blocking before breakpoint | Disable auth, check port 6565 |
| Proto changes have no effect | Generated code not regenerated | Run `./proto.sh` or equivalent |

### Step 4 — Suggest a minimal fix

- Explain *why* the fix works.
- Read the file first, then show the exact change.
- Provide a verification step after every fix.

### Step 5 — Verify

\`\`\`bash
# Confirm service starts cleanly
go run main.go 2>&1 | jq 'select(.level == "ERROR")'

# Confirm gRPC layer is reachable
grpcurl -plaintext localhost:6565 list

# Call a specific method (adjust service and method for your use case)
grpcurl -plaintext \
  -d '{"rules": {"json": "{}"}}' \
  localhost:6565 \
  accelbyte.matchmakingv2.matchfunction.MatchFunction/GetStatCodes
\`\`\`

---

## Write Mode

### Audience

Junior developers and game developers with limited backend experience. Avoid assuming knowledge
of gRPC, protobuf, or IAM. Use plain language. VS Code-centric but include notes for other IDEs.

### Required sections

1. Overview + architecture diagram
2. Project structure reference (file-to-responsibility table, port table)
3. Prerequisites (language-specific)
4. Environment setup (.env, key variables, when to disable auth locally)
5. Running the service (terminal + VS Code task)
6. Attaching the debugger (VS Code launch config, other IDEs/headless)
7. Breakpoints and inspection (placement table, stepping shortcuts, conditional breakpoints)
8. Reading logs (format, levels, gRPC pairs, jq)
9. Common issues (symptom / cause / fix per issue)
10. Testing manually (grpcurl, trigger AGS feature, Postman collection)
11. AI-assisted debugging (this skill, MCP servers, prompting tips)
12. Tips and best practices

### Before writing, always read first

1. Existing `DEBUGGING_GUIDE.md` if present — update, do not replace accurate content.
2. `main.go` (or equivalent entry point) for ports, startup sequence, and env vars.
3. Service implementation file to understand the business logic layer.
4. `.vscode/launch.json` for the debug configuration name and settings.
5. The `.proto` file for service method names.

MCP servers​

The app template ships with MCP server configurations in .vscode/mcp.json (where present). These give AI assistants direct access to AccelByte-specific knowledge:

ServerWhat it provides
ags-extend-sdk-mcp-serverKnowledge of AccelByte Extend SDK symbols, types, and usage patterns
ags-api-mcp-serverLive AGS REST API access (requires AB_BASE_URL in your environment)

For general AI prompting tips when debugging Extend apps, see Debugging with AI assistance in the common debugging guide for Extend apps.

Tips and best practices​

For general tips — log levels, disabling auth, conditional breakpoints, VS Code panels, and port checks — see Tips and best practices in the common debugging guide for Extend apps.

Extend Override-specific tips:

  • Disable auth for local development. Set PLUGIN_GRPC_SERVER_AUTH_ENABLED=false in your .env while debugging business logic. Re-enable it before deploying to verify auth behavior end to end.

  • Regenerate proto bindings after every .proto change. Editing the .proto file without regenerating is one of the most common sources of confusing compile or runtime errors. See the language guide for the exact regeneration command.

  • Use grpcurl for quick manual tests. Because there is no HTTP/REST layer, grpcurl is the fastest way to fire a single call and observe the result without needing to trigger the full AGS flow.

Language-specific guides​

The sections above cover concepts and workflows that apply to all languages and all Override use cases. For setup instructions, project structure, run commands, debugger configuration, and language-specific troubleshooting, see the dedicated guide for your language:

References​

Last updated on
On this page