Extend Service Extension のローカルデバッグガイド

Last updated on April 8, 2026

Overview

This guide walks you through debugging an Extend Service Extension 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.

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 request flows through the service

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

Game Client / AGS
       │  HTTP (REST)
       ▼
 gRPC-Gateway  (port 8000)   ← translates HTTP ↔ gRPC
       │  gRPC
       ▼
 gRPC Server   (port 6565)   ← your business logic lives here
       │
       ▼
 AccelByte CloudSave / other AGS services

Port summary:

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

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

Symptom	Most likely layer	Where to look first
Service won't start	Environment / credentials	`.env` file, IAM client credentials
HTTP 4xx responses	Auth interceptor	`service.proto` permission definitions
HTTP 5xx responses	Business logic / storage	Service and storage implementation files
Debugger never pauses	Port conflict or build mode	Check running processes on ports 6565/8000
Proto changes ignored	Generated code stale	Regenerate protobuf bindings

Environment setup

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

Extend Service Extension-specific variable: `BASE_PATH`

Extend Service Extension requires one additional environment variable that other Extend app types do not:

# URL prefix this service is served under. Must start with /.
BASE_PATH=/guild

Variable	Purpose	Example
`BASE_PATH`	URL prefix for the gRPC-Gateway HTTP endpoints. Must start with `/`.	`/guild`

BASE_PATH controls the URL path at which the gRPC-Gateway serves all HTTP endpoints. Without it the service cannot start.

Running the service locally

For VS Code task and terminal run instructions, see Running the service locally in the generic guide.

Confirming the gRPC-Gateway is up

Once the service starts, open http://localhost:8000<BASE_PATH>/apidocs/ in your browser. If Swagger UI appears and lists your endpoints, the gRPC-Gateway is also running correctly.

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 generic guide.

For the Service Extension 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 generic guide.

For the recommended breakpoint locations in your SE 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 generic guide.

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 generic guide.

The issues below are specific to Extend Service Extension.

Service fails to start — `BASE_PATH` not set

Symptom:

{"level":"ERROR","msg":"BASE_PATH envar is not set or empty"}

Cause: The BASE_PATH environment variable is missing or does not start with /.

Fix: Add BASE_PATH=/guild (or any path starting with /) to your .env and restart.

Endpoint returns `500 Internal Server Error`

Symptom: HTTP 500 or gRPC status Internal.

How to diagnose:

Check the terminal output for an ERROR log around the time of the request.
Set a breakpoint inside the failing service method.
Step into the storage calls to check whether CloudSave is returning an error.
Verify the namespace in your request matches a real namespace in your AGS environment.

Proto changes have no effect

Symptom: You edited service.proto 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, or run ./proto.sh directly, then restart the service.

Testing endpoints manually

Swagger UI

Navigate to http://localhost:8000<BASE_PATH>/apidocs/ in your browser. The built-in Swagger UI lets you read the API documentation and send requests directly from the browser without any extra setup.

Postman

The demo/ directory in the repository contains Postman collection files (*.postman_collection.json) with pre-built requests. Import them into Postman, then update the environment variables — baseUrl, namespace, and token — to match your local setup.

curl and grpcurl

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

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

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

The Extend Service Extension app template 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 apps.

The skill file is available in each language's template repository:

Language	SKILL.md
Go	`.claude/skills/debugging-guide/SKILL.md`
C#	`.claude/skills/debugging-guide/SKILL.md`
Java	`.claude/skills/debugging-guide/SKILL.md`
Python	`.claude/skills/debugging-guide/SKILL.md`

Once the skill is active, invoke it by typing one of the following in your AI chat:

Intent	What to type
Debug a live issue	`/debugging-guide Go — getting 500 on GetGuildProgress`
Write or update the debugging guide	`/debugging-guide write Go`
Let the AI decide	Describe 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 the full skill file for reference. You can copy and save this as .claude/skills/debugging-guide/SKILL.md in your own Extend app repository.

View the full debugging skill (SKILL.md)

---
name: debugging-guide
description: >
  Expert guide writer and debugging assistant for AccelByte Extend Service Extension apps.
  Use when a developer asks for help debugging their Extend service, diagnosing startup or
  runtime errors, understanding logs, setting up a debugger, or when writing or updating a
  DEBUGGING_GUIDE.md for an Extend app. Covers Go but the workflow is applicable 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(curl *), Bash(grpcurl *), Bash(jq *)
---

# Debugging Guide Skill — Extend Service Extension

You are an expert backend developer and technical writer specializing in AccelByte Gaming
Services (AGS) Extend 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 Service Extension 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: *"Do you want help debugging a live
issue, or do you want me to write/update the debugging guide?"*

---

## Architecture Context

Every Extend Service Extension app shares this layered architecture:

\`\`\`
Game Client / AGS
       │  HTTP (REST)
       ▼
 gRPC-Gateway  (port 8000)   ← translates HTTP ↔ gRPC
       │  gRPC
       ▼
 gRPC Server   (port 6565)   ← business logic lives here
       │
       ▼
 AccelByte CloudSave / other AGS services
\`\`\`

Key environment variables:

| Variable | Purpose |
|---|---|
| `AB_BASE_URL` | AccelByte environment base URL |
| `AB_CLIENT_ID` / `AB_CLIENT_SECRET` | OAuth client credentials |
| `BASE_PATH` | URL prefix (must start with `/`) |
| `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.
- Returns **4xx** → auth interceptor and proto-defined permissions.
- Returns **5xx** → business logic and storage layer.
- 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_|BASE_PATH|PLUGIN_GRPC|LOG_LEVEL'`
4. Check ports: `ss -tlnp | grep -E '6565|8000|8080'`

### Step 3 — Common-issue checklist

| Symptom | Likely cause | Where to look |
|---|---|---|
| `BASE_PATH envar is not set or empty` | Missing/invalid `BASE_PATH` | `main.go` startup |
| `unable to login using clientId and clientSecret` | Wrong credentials or unreachable `AB_BASE_URL` | `main.go` → OAuth login |
| All requests return `401 Unauthenticated` | Token missing/expired or wrong permission | Auth interceptor; `service.proto` |
| `500 Internal Server Error` | CloudSave call failed or data parse error | Storage and service files |
| Breakpoints never hit | Wrong port, auth failure before breakpoint | Disable auth, check port conflicts |
| Proto changes have no effect | Generated code not regenerated | Run `./proto.sh` |

### 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 endpoint responds
curl -s http://localhost:8000/guild/v1/admin/namespace/mygame/progress | jq .

# Confirm gRPC layer directly
grpcurl -plaintext localhost:6565 list
\`\`\`

---

## 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, why 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 endpoints manually (Swagger UI, curl, Postman, grpcurl)
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 and storage files to understand the business logic layer.
4. `.vscode/launch.json` for the debug configuration name and settings.
5. `.vscode/mcp.json` for configured MCP servers.
6. `service.proto` for endpoint names and permission requirements.

MCP servers

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

| Server | What it provides | |---|---|---| | (ags-extend-sdk-mcp-server)[https://github.com/AccelByte/ags-extend-sdk-mcp-server] | Knowledge of AccelByte Extend SDK symbols, types, and usage patterns | | (ags-api-mcp-server)[https://github.com/AccelByte/ags-api-mcp-server] | Live 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 generic guide.

Paste logs and ask for a summary.

"Here are 30 lines of JSON logs from my Extend Service. Which request failed, and what caused it?"

Ask for a targeted test once you understand the bug.

"Write a Go unit test for GetGuildProgress that covers the case where CloudSave returns a not-found error. Use the mocks in pkg/service/mocks/."

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 generic guide.

Extend Service Extension-specific tips:

Regenerate proto bindings after every .proto change. Editing service.proto without running ./proto.sh afterwards is one of the most common sources of confusing compile or runtime errors. See each language guide for the exact regeneration command.
Check service.proto for permissions. When a request returns 401 Unauthenticated with a real token, check the permission.resource and permission.action fields on the relevant RPC in service.proto — the token may lack the exact permission the endpoint requires.

Language-specific guides

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

Overview​

How a request flows through the service​

Environment setup​

Extend Service Extension-specific variable: BASE_PATH​

Running the service locally​

Confirming the gRPC-Gateway is up​

Attaching the debugger​

Setting breakpoints and inspecting state​

Reading logs​

Common issues​

Service fails to start — BASE_PATH not set​

Endpoint returns 500 Internal Server Error​

Proto changes have no effect​

Testing endpoints manually​

Swagger UI​

Postman​

curl and grpcurl​

Debugging with AI assistance​

Using the debugging skill​

MCP servers​

Tips and best practices​

Language-specific guides​

References​