Telegram debugging

telegram debugging

reproduce or narrow the failure before changing code. fix the root cause without unrelated refactoring.

workflow

1. establish the user action, expected and actual behavior, chat type, event or command, current state, aiogram version, recent changes, and relevant logs or traceback.
2. make a focused test fail on the reported behavior before the fix. use an existing test when it proves the symptom; otherwise create the smallest regression test when feasible.
3. classify the failure: registration or filter mismatch, callback payload or answer, FSM transition or cleanup, stale data, message edit, startup mode, middleware dependency, permission, race or double action, or telegram API handling.
4. trace routing end to end: router inclusion and order, exact filters, command or callback prefix, state constraints, catch-all handlers, and middleware.
5. trace data and state end to end: service inputs, repository query, transaction lifecycle, entity freshness, permissions, idempotency, and cleanup.
6. for webhook or polling failures, confirm one startup mode, the real entrypoint, config loading, lifecycle hooks, and import safety.
7. change the smallest area that explains the evidence. do not swallow telegram exceptions or repair the visible response while leaving state or data corrupt.
8. add regression coverage for the failed route, payload, transition, stale entity, exception, or repeated action.
9. use telegram-docs-check when an API exception, retry rule, signature, or payload contract is version-sensitive.
10. use aiogram-bot-verify after code changes.

completion requires an evidence-backed root cause, a minimal fix, regression coverage or a stated reason it is infeasible, and safe verification.

guardrails

never guess past unchecked routing or state, use production tokens or live telegram requests in tests, start polling or a webhook during imports, or broaden a bug fix into an architecture rewrite.