Local debugging guide — Python

Last updated on March 20, 2026

This guide covers everything specific to debugging an Extend Service Extension app written in Python. For concepts that apply to all languages — architecture, environment variables, log format, and common issues — see the main debugging guide.

Prerequisites​

  • Python 3.10 or later — verify with:

    python --version
    # Expected: Python 3.10.x or later

  • VS Code Python extension (ms-python.python) — install from the VS Code marketplace or accept the recommended extensions prompt when you open the repository.

  • debugpy — the Python debug adapter for VS Code:

    pip install debugpy

  • AccelByte credentials — AB_BASE_URL, AB_CLIENT_ID, AB_CLIENT_SECRET, and BASE_PATH. See Environment setup in the main guide.

Project structure​

src/
└── app/
    ├── __main__.py                            # Entry point
    ├── services/
    │   └── my_service.py                      # Your business logic
    └── ...
proto/
└── app/
    └── service.proto                          # gRPC API definition
FileWhat it does
src/app/__main__.pyEntry point — starts the gRPC server and gRPC-Gateway.
src/app/services/my_service.pyYour business logic — implements the gRPC service methods.
src/accelbyte_grpc_plugin/interceptors/authorization.pyValidates every incoming request's IAM token and permission.
proto/app/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)

python -m app

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 that uses debugpy:

{
  "name": "Debug: Service",
  "type": "python",
  "request": "launch",
  "module": "app",
  "cwd": "${workspaceFolder}/src",
  "envFile": "${workspaceFolder}/.env"
}

Steps:

  1. Fill in .env (see Environment setup).
  2. Open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D).
  3. Select "Debug: Service" from the dropdown.
  4. Press F5.

Other IDEs — remote debugpy attach​

Start the app with debugpy listening on port 5678:

export $(grep -v '^#' .env | xargs)
python -m debugpy --listen 5678 --wait-for-client -m app

The process pauses until a debugger connects. Attach from PyCharm, a remote debugger, or a second VS Code window using:

{
  "name": "Attach: Remote",
  "type": "python",
  "request": "attach",
  "connect": { "host": "localhost", "port": 5678 }
}

Where to put breakpoints​

What you want to investigateFile and location
A specific REST endpoint being calledservices/my_service.py — top of the relevant method
Auth/token validation failureaccelbyte_grpc_plugin/interceptors/authorization.py — the request interception point
Data not saving or loading correctlyThe storage or repository module used in your service
Service not starting at allapp/__main__.py — the server setup block

Conditional breakpoint syntax​

Right-click a breakpoint → Edit Breakpoint → enter a Python expression, for example:

request.guild_id == "guild_001"

The debugger only pauses when the condition is true.

Reading logs​

Pipe output through jq for readable JSON logs:

python -m app 2>&1 | jq '.'

# Show only ERROR lines
python -m app 2>&1 | jq 'select(.level == "ERROR")'

Testing endpoints manually​

curl​

# Create or update guild progress
curl -s -X POST \
  "http://localhost:8000/guild/v1/admin/namespace/mygame/progress" \
  -H "Content-Type: application/json" \
  -d '{"guildProgress": {"guildId": "guild_001", "namespace": "mygame"}}' | jq .

# Get guild progress
curl -s "http://localhost:8000/guild/v1/admin/namespace/mygame/progress/guild_001" | jq .

Add -H "Authorization: Bearer <your-token>" when PLUGIN_GRPC_SERVER_AUTH_ENABLED=true.

grpcurl (gRPC layer directly)​

# List available services
grpcurl -plaintext localhost:6565 list

# Call a method directly
grpcurl -plaintext \
  -d '{"namespace":"mygame","guildProgress":{"guildId":"guild_001"}}' \
  localhost:6565 service.Service/CreateOrUpdateGuildProgress

Python-specific troubleshooting​

Proto changes have no effect​

Symptom: You edited proto/app/service.proto but the generated stubs haven't updated.

Fix: Re-run the proto generation script:

./proto.sh

Restart the service after re-generation.

ModuleNotFoundError for app​

Symptom: Running python -m app gives ModuleNotFoundError: No module named 'app'.

Cause: The working directory is wrong. The module lives under src/.

Fix:

cd src
python -m app

Or set PYTHONPATH:

PYTHONPATH=src python -m app

debugpy not found​

Symptom: VS Code says debugpy is not installed.

Fix:

pip install debugpy
# If using a virtual environment, activate it first:
source .venv/bin/activate && pip install debugpy

Checking for port conflicts​

ss -tlnp | grep -E '6565|8000|8080|5678'

Kill any stale process and start again.

AI assistance​

The app template ships with a Claude agent skill at .claude/skills/debugging-guide/SKILL.md. Copy the full skill file into your own repository and activate it in your AI assistant.

For the full skill content and prompting tips, see the AI assistance section in the main guide.

References​

Last updated on
On this page