Local debugging guide — Python

Last updated on April 8, 2026

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

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"
}

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

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

For conditional breakpoint syntax, see the Python language guide.

Reading logs​

For jq log filtering, see the Python 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.

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​

See Checking for port conflicts in the Python 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