Local debugging — Python
This guide covers everything specific to debugging an Extend app written in Python. For concepts that apply to all Extend apps and languages — environment variables, VS Code debug workflow, log reading, and common issues — see the Extend local 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. See Environment setup in the main guide.
VS Code launch configuration
The repository ships with a ready-to-use launch configuration in .vscode/launch.json:
{
"name": "Debug: Service",
"type": "python",
"request": "launch",
"module": "app",
"cwd": "${workspaceFolder}/src",
"envFile": "${workspaceFolder}/.env"
}
The exact module and cwd values are provided by the app template's .vscode/launch.json.
Steps:
- Fill in
.env(see Environment setup). - Open the Run and Debug panel (
Ctrl+Shift+D/Cmd+Shift+D). - Select "Debug: Service" from the dropdown.
- 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 or a second VS Code window:
{
"name": "Attach: Remote",
"type": "python",
"request": "attach",
"connect": { "host": "localhost", "port": 5678 }
}
Conditional breakpoint syntax
Right-click a breakpoint → Edit Breakpoint → enter a Python expression. Example:
request.user_id == "user_001"
The debugger only pauses when the condition is true.
Reading logs with jq
# Pretty-print everything
python -m app 2>&1 | jq '.'
# Show only ERROR lines
python -m app 2>&1 | jq 'select(.level == "ERROR")'
For an overview of the log format and log levels, see Reading and understanding logs in the main guide.
Python-specific troubleshooting
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.