Local Debugging Guide for Extend Override — Python

Last updated on April 10, 2026

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

Extend local debugging guide — common concepts for all Extend app types
Python language setup guide — Python prerequisites, debugpy, jq, and Python-specific troubleshooting
Extend Override debugging guide — Override-specific concepts for all languages

The examples in this guide use the matchmaking use case (matchmaking-function-grpc-plugin-server-python). 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-python/
├── proto.sh                             # Regenerate protobuf bindings
├── .env.template                        # Environment variable template
├── .vscode/
│   ├── launch.json                      # VS Code debug configuration
│   └── tasks.json                       # VS Code tasks (Run: App, Proto: Generate, etc.)
├── proto/
│   └── matchFunction.proto              # Protobuf definition
└── src/
    ├── matchFunction_pb2.py             # Generated protobuf types (do not edit)
    ├── matchFunction_pb2_grpc.py        # Generated gRPC servicer (do not edit)
    └── app/
        ├── __main__.py                  # Entry point — registers service, configures auth
        ├── ctypes.py                    # GameRules dataclass and ValidationError
        ├── utils.py                     # Environment helpers
        └── services/
            └── matchFunction.py         # AsyncMatchFunctionService — your override logic

File	What it does
`src/app/__main__.py`	Entry point — starts the gRPC server, registers `AsyncMatchFunctionService`, wires the auth interceptor.
`src/app/services/matchFunction.py`	Your override logic — async gRPC handler implementing GetStatCodes, ValidateTicket, EnrichTicket, MakeMatches, BackfillMatches.
`src/app/ctypes.py`	`GameRules` dataclass and `ValidationError`.
`src/matchFunction_pb2.py`	Generated protobuf message types. Do not edit directly.
`src/matchFunction_pb2_grpc.py`	Generated gRPC servicer base class. Do not edit directly.
`proto/matchFunction.proto`	Protobuf definition — source of truth for service methods.

Port numbers (configured in __main__.py):

Port	Purpose
`6565`	gRPC server — receives calls from AGS
`8080`	Prometheus metrics endpoint (`/metrics`)

Running the service locally

From the terminal

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

PYTHONPATH=src python -m app

From VS Code

Use Terminal → Run Task → "Run: App". This task is defined in .vscode/tasks.json and sets PYTHONPATH=src automatically. It expects a virtual environment at venv/ inside the project root.

Setting up a virtual environment

If you do not have a venv/ directory yet:

python -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Confirming the service is up

You should see log output similar to:

INFO:app:using AccelByte Python SDK x.x.x
INFO:asyncio:gRPC server started on port 6565

Verify that the gRPC server is reachable:

grpcurl -plaintext localhost:6565 list

Attaching the debugger

VS Code (recommended)

The repository ships with a ready-to-use launch configuration in .vscode/launch.json:

{
  "name": "Debug: App",
  "type": "debugpy",
  "request": "launch",
  "module": "app",
  "cwd": "${workspaceFolder}",
  "envFile": "${workspaceFolder}/.env",
  "env": {
    "PYTHONPATH": "src"
  },
  "console": "integratedTerminal",
  "justMyCode": true
}

Follow the attaching the debugger steps in the common debugging guide, then select "Debug: App" from the dropdown.

Stepping into library code

"justMyCode": true skips into debugpy and third-party frames. Set it to false if you need to step into the accelbyte_grpc_plugin interceptor or generated gRPC code.

Other IDEs — remote debugpy attach

Start the app with debugpy listening on port 5678:

export $(grep -v '^#' .env | xargs)
PYTHONPATH=src 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": "debugpy",
  "request": "attach",
  "connect": { "host": "localhost", "port": 5678 }
}

Where to put breakpoints

What you want to investigate	File and location
A specific gRPC method being called	`src/app/services/matchFunction.py` — top of the relevant async method
Streaming match logic	`src/app/services/matchFunction.py` — inside the `async for request in request_iterator` loop in `MakeMatches`
Rules parsing	`src/app/services/matchFunction.py` — `json.loads(rules_json)` lines
Auth / token validation failure	`src/accelbyte_grpc_plugin/interceptors/authorization.py` — interceptor entry
Service not starting at all	`src/app/__main__.py` — the `sdk.initialize(...)` and `auth_service.login_client_async(...)` calls

For conditional breakpoint syntax, see the Python language guide.

Reading logs

The service uses Python's standard logging module. For jq log filtering (if your service outputs JSON logs), see the Python language guide.

To see only error-level output while the service is running:

PYTHONPATH=src python -m app 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.

Python-specific troubleshooting

Proto changes have no effect

Symptom: You edited proto/matchFunction.proto but the generated stubs have not updated.

Cause: The generated files src/matchFunction_pb2.py and src/matchFunction_pb2_grpc.py have not been regenerated.

Fix: Run the "Proto: Generate" VS Code task, or:

./proto.sh

Restart the service after regeneration.

`ModuleNotFoundError: No module named 'app'`

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

Cause: PYTHONPATH is not set, so Python cannot find the app module inside src/.

Fix: Always prefix the command with PYTHONPATH=src:

PYTHONPATH=src python -m app

The VS Code launch config and "Run: App" task handle this automatically.

`PLUGIN_GRPC_SERVER_AUTH_ENABLED` — auth rejects all calls

Symptom: Every gRPC call returns unauthenticated when testing locally.

Fix: Add PLUGIN_GRPC_SERVER_AUTH_ENABLED=false to your .env file. This disables the IAM interceptor so you can test without a valid token. Remember to re-enable it before deploying.

`debugpy` not found

Symptom: VS Code says debugpy is not installed, or the launch config fails.

Fix:

# Activate your virtual environment first, then install
source venv/bin/activate
pip install debugpy

Checking for port conflicts

See Checking for port conflicts in the Python 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 case	Python service file	Proto file
Matchmaking	`src/app/services/matchFunction.py`	`proto/matchFunction.proto`
Cloud Save Validator	See repo README	See repo README
Lootbox Roll	See repo README	See repo README
Profanity Filter	See repo README	See repo README
Revocation	See repo README	See repo README
Rotating Shop Items	See repo README	See repo README
Session DSM	See repo README	See repo README
Session Manager	See repo README	See repo README
Challenge Assignment	See repo README	See repo README

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

Project structure​

Running the service locally​

From the terminal​

From VS Code​

Confirming the service is up​

Attaching the debugger​

VS Code (recommended)​

Other IDEs — remote debugpy attach​

Where to put breakpoints​

Reading logs​

Testing the override manually​

Python-specific troubleshooting​

Proto changes have no effect​

ModuleNotFoundError: No module named 'app'​

PLUGIN_GRPC_SERVER_AUTH_ENABLED — auth rejects all calls​

debugpy not found​

Checking for port conflicts​

AI assistance​

Service file reference by use case​

References​