Обновлено: октябрь 2026. Telegram-бот падает чаще всего по одним и тем же причинам. Старый webhook блокирует polling. FSM-состояние зависает в памяти. Supabase отваливается по таймауту. Токен бота приехал из BotFather с невидимым пробелом. Разберем десять багов поштучно. Под каждым идет симптом, корень проблемы и готовый дебаг-промпт для Windsurf, который чинит за минуты вместо часов.
TL;DR. Десять багов покрывают 90% случаев, когда телеграм бот для бизнеса перестает отвечать. Пять из них связаны с инфраструктурой (webhook, polling, ngrok, Supabase, токен), еще пять с кодом (FSM, magic filters, error 500, утечки памяти, состояния). Под каждый дан промпт для Windsurf, который локализует баг и предлагает фикс.
Какие баги Telegram-ботов встречаются чаще всего
Из десяти самых частых обращений за консультацией восемь связаны с конфликтом polling и webhook, FSM-памятью и токеном. Остальные два касаются Supabase и magic filters.
Если разобрать чужой код после жалобы «не работает», статистика складывается одинаково. Конфликт polling и webhook ловят почти все, кто переключал режимы. FSM-зависание встречается, когда стораджем оставили дефолтный MemoryStorage. Невидимый пробел в токене — болезнь начинающих, кто копирует токен из BotFather через буфер.
| # | Баг | Симптом | Где корень | Среднее время на фикс |
|---|---|---|---|---|
| 1 | Бот не отвечает после рестарта | /start висит, ответов нет | Старый webhook не сброшен | 5 минут |
| 2 | FSM-состояние зависает | Юзер залип на шаге, /start не помогает | MemoryStorage + ребут | 20 минут |
| 3 | Webhook не регистрируется | setWebhook возвращает false | HTTPS-сертификат или secret | 15 минут |
| 4 | Polling vs webhook | Conflict: terminated by other getUpdates | Параллельные процессы | 10 минут |
| 5 | Supabase connection timeout | Подвисает каждые 5-10 минут | Pool overflow | 30 минут |
| 6 | Невидимый пробел в токене | 401 Unauthorized | Копирование из BotFather | 2 минуты |
| 7 | Magic filters не срабатывают | Хендлер игнорирует апдейт | Неверный тип filter | 15 минут |
| 8 | Ngrok ломает webhook | Через 30 минут тишина | Туннель перевыпустился | 5 минут |
| 9 | Апдейты пропадают при 500 | Сообщения приходят с лагом | Очередь retry в Telegram | подождать |
| 10 | Утечка памяти за сутки | Бот падает по OOM | Несбрасываемые сессии | 1 час |
Что делать если бот не отвечает после рестарта
Чаще всего виноват висящий webhook от прошлого запуска. Telegram шлет апдейты на старый URL, polling в локальной разработке не получает ничего. Лечится одной командой deleteWebhook.
При запуске polling Telegram не должен иметь активных вебхуков на боте. Если webhook стоял раньше, его надо сбросить с флагом drop_pending_updates, иначе старая очередь догонит вас на проде. Это самая частая причина «бот не отвечает» по статистике запросов в наш чат вайбкодеров.
Симптом простой. Вы запустили скрипт, в консоли «Bot started», в Telegram пишете /start, в ответ молчание. Логи чистые, traceback пустой. На самом деле Telegram уверен, что у бота есть webhook, и шлет обновления туда. Polling висит вхолостую.
Дебаг-промпт для Windsurf под этот случай:
Бот на aiogram 3 запускается в режиме polling, но не получает
ни одного апдейта. Логи чистые. Проверь main.py: убедись что
перед dp.start_polling() вызывается await bot.delete_webhook(
drop_pending_updates=True). Если вызова нет — добавь. Также
покажи команду curl для ручной проверки getWebhookInfo через
Telegram Bot API.Windsurf откроет файл, найдет start_polling, добавит сброс webhook и подскажет curl-запрос вида https://api.telegram.org/bot<TOKEN>/getWebhookInfo. Если в ответе URL не пустой, webhook висит, лечите его.
Почему FSM-состояние зависает и пользователь застревает
FSM на MemoryStorage теряется при каждом рестарте процесса. Юзер ушел на шаг «введите телефон», бот перезагрузился, новый /start игнорируется. Перенесите state в Redis или Supabase.
MemoryStorage в aiogram 3 живет в оперативной памяти процесса. Перезапустили бота, передеплоили на Railway, упал воркер. Все FSM-стейты пропали. Юзер вернулся через час, нажал /start, но хендлер ждет от него телефон в шаге «contact_input» и просто игнорирует команду.
Этот баг особенно болит, когда вы решили создать бота поддержки с многошаговыми сценариями. Заявка, опрос, регистрация на услугу. Все они идут через FSM. Любой ребут роняет половину открытых сессий.
Дебаг-промпт:
Бот использует FSM на MemoryStorage. После каждого деплоя
юзеры пишут что не могут продолжить с того шага где остановились.
Покажи как:
1) переключить storage с MemoryStorage на RedisStorage
2) добавить хендлер /cancel который сбрасывает любой стейт
3) поставить TTL на FSM-стейт 30 минут чтобы зависшие сессии
очищались сами
Стек: aiogram 3.18, Redis уже подключен к проекту,
переменная REDIS_URL в .env.Готового решения хватит на 20 минут. RedisStorage переживает рестарты, /cancel спасает залипшие сессии, TTL не дает памяти расти бесконечно. Для serverless-окружений лучше Redis на Upstash, бесплатно до 10К запросов в день.
Как починить если webhook не регистрируется
setWebhook молча возвращает false по трем причинам. Не-HTTPS URL, невалидный TLS-сертификат, или secret_token не совпадает с заголовком. Проверка занимает три curl-запроса.
Telegram принимает webhook только по HTTPS и только если сертификат валиден. Self-signed работает, но требует загрузки .pem-файла при регистрации. Бесплатный сертификат от Let's Encrypt снимает 90% проблем сразу. Cloudflare с проксированием иногда отдает неверный certificate chain.
В коде проверьте три вещи. URL точно начинается с https://. Путь после домена совпадает с тем, что слушает сервер aiohttp. Webhook secret в заголовке X-Telegram-Bot-Api-Secret-Token совпадает с тем, что вы передали в setWebhook.
Дебаг-промпт:
setWebhook возвращает false без описания ошибки. Бот на aiogram 3,
сервер aiohttp на порту 8080, домен через Cloudflare. Помоги
продебажить пошагово:
1) curl-запрос к getWebhookInfo с расшифровкой last_error_message
2) проверка что webhook_path в коде совпадает с тем что
зарегистрирован у Telegram
3) проверка secret_token в SimpleRequestHandler
4) тест что сервер реально доступен снаружи по HTTPS
Покажи команды и куда смотреть в логах aiohttp.Поле last_error_message в ответе getWebhookInfo обычно дает ключ к проблеме. «SSL: WRONG_VERSION_NUMBER» значит, что порт не отдает HTTPS. «Wrong response from the webhook: 404» — путь не тот. «Secret token is invalid» — несовпадение secret_token.
Почему polling конфликтует с webhook
Telegram разрешает только один способ доставки апдейтов на бота. Запустили polling рядом с зарегистрированным webhook? Получите «Conflict: terminated by other getUpdates request».
Когда вы создаете ии для создания тг бота через AI-агента, тот не всегда знает текущее состояние бота в Telegram. Агент пишет код под polling, а у вас на проде живет webhook от предыдущей итерации. В итоге два процесса дерутся за апдейты, оба падают.
Симптом в логах: aiogram.exceptions.TelegramConflictError: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running. Иногда апдейты приходят к одному процессу, иногда к другому, рандомно. Хендлеры срабатывают через раз.
Дебаг-промпт:
В логах TelegramConflictError. Проверь:
1) что в Telegram сейчас зарегистрировано через getWebhookInfo
2) есть ли где-то еще запущенный процесс бота (ps aux | grep python)
3) добавь в startup-код бота явный bot.delete_webhook(
drop_pending_updates=True) перед polling
4) если бот деплоится на Railway/Render — проверь что старая
ревизия точно остановлена, иногда висит зомби-процесс
Покажи конкретные команды для проверки на Linux-сервере.На Railway часто помогает явный рестарт деплоймента. На VPS поможет pkill -f bot_main.py перед запуском. Если используете systemd, проверьте Restart=always и что юнит не запущен дважды.
Что делать с Supabase connection timeout в боте
Подключения копятся быстрее чем закрываются. Pool переполняется, новые запросы висят. Лечится pgbouncer в transaction mode и pool_size в районе 5-10.
Supabase дает по 60 одновременных подключений на проект на бесплатном тарифе. Чат боты для бизнеса с активным трафиком выжирают этот лимит за час. Особенно если каждый хендлер открывает новое соединение и забывает закрыть. Через час бот ловит connection timeout и молчит.Симптом плавающий. Бот работает нормально первый час, потом ответы начинают приходить с задержкой 10-30 секунд, потом часть сообщений теряется. В логах Supabase видно too many connections for role.
Дебаг-промпт:
Бот на aiogram 3 + asyncpg + Supabase. После часа работы
начинаются connection timeout и потери апдейтов. Помоги:
1) переключить подключение с прямого порта 5432 на pooler 6543
(transaction mode pgbouncer)
2) выставить pool_size=10, max_overflow=5, pool_pre_ping=True
3) добавить middleware которое получает соединение в начале
хендлера и возвращает в pool в конце через async context manager
4) логгировать сколько соединений сейчас открыто каждые 5 минут
Покажи готовый код middleware для aiogram 3.Транзакционный pooler Supabase на порту 6543 решает 80% подобных кейсов сразу. Соединения переиспользуются между запросами, пик нагрузки выдерживается без падений. Бесплатный тариф после переключения держит примерно 200 одновременных пользователей.
Пять «тихих» багов которые ломают бота незаметно
Эти баги не выкидывают traceback и не дают красных строк в логах. Бот просто работает странно. Диагностика по симптомам, не по ошибкам.
Самые подлые баги в Telegram-боте те, где код выполняется без ошибок, но делает не то. Невидимый пробел в токене, неверный тип в magic filter, истекший ngrok-туннель. Каждый из этих случаев лечится за пять минут, если знать где смотреть.
Невидимый пробел в токене
Скопировали токен из BotFather через мобильную клавиатуру, в начало или конец прилип пробел. Бот стартует, через секунду падает с Unauthorized. Лечится открытием .env в редакторе с подсветкой непечатных символов и token.strip() в коде. Промпт: «Добавь strip() при чтении BOT_TOKEN из переменной окружения, валидируй формат регуляркой ^\d{8,10}:[A-Za-z0-9_-]{35}$».
Magic filters не срабатывают
В aiogram 3 фильтр F.text == "hello" сработает только на текстовые сообщения. Если юзер прислал стикер с подписью «hello», хендлер пропустит апдейт. Аналогично F.photo не ловит документ-изображение. Дебаг-промпт: «Покажи список content_types которые приходят на текущий хендлер, добавь логгирование message.content_type в начало роутера для отладки».
Ngrok-туннель ломает webhook
Бесплатный ngrok дает URL на 30 минут или до перезапуска. URL поменялся, а webhook у Telegram остался старый. Промпт: «Сделай скрипт на bash который при старте ngrok автоматически забирает публичный URL через ngrok API на localhost:4040 и вызывает setWebhook у Telegram».
Апдейты приходят с задержкой 30 секунд
Если хендлер вернул 500-ю ошибку, Telegram ставит апдейт в retry-очередь и шлет повторно. Сначала через 3 секунды, потом 10, потом 30. Не паникуйте и не перезапускайте бота. Подождите минуту, очередь рассосется. Промпт: «Добавь global error handler в роутер чтобы ловить exception и возвращать 200 OK с логгированием, а не падать на 500».
Утечка памяти за сутки
Бот живет сутки, потом падает по OOM. Чаще всего виноваты несбрасываемые Bot() инстансы внутри хендлеров или забытые aiohttp.ClientSession. Промпт: «Запусти memray на работающем процессе бота, найди топ-5 объектов по памяти, покажи где они создаются».
Как Windsurf ускоряет дебаг бота
Cascade в Windsurf читает весь проект, ищет связи между файлами и выдает правку с пояснением. Ручной дебаг занимает час, через AI — около 10-15 минут на стандартный баг.
ИИ для создания тг бота полезен не только на этапе генерации кода. Дебаг в нем идет быстрее за счет того, что агент видит весь контекст проекта сразу. Не нужно копировать файлы туда-сюда. Windsurf и Cursor умеют запускать команды и читать вывод прямо из чата.
Базовая модель под дебаг — Claude Sonnet 4.6 за 3 доллара на миллион токенов входа. Для сложных случаев — Claude Opus 4.7 с 87.6% на SWE-bench. Для бюджетной работы — DeepSeek V4 Pro Max за 43 цента на миллион при том же качестве кода 80.6% на SWE-bench. Параметры есть в нашем разборе моделей.
Максим: «Мог засесть до пяти ночи и править одну функцию, которая не работала. Если бы не терпение — я уже испотел, и хотелось это все закрыть. Но я понимал, что это можно решить и нужно решить, чтобы идти дальше. С Windsurf этот же баг я бы поймал часа за полтора, не за восемь».
Включите режим Cascade write для автопатчей или read для просмотра предложений. Read безопаснее, write быстрее. На незнакомой кодовой базе всегда начинайте с read.
Какой шаблон дебаг-промпта работает универсально
Хороший промпт дает агенту стек, симптом, лог и желаемый результат. Без логов агент гадает, без стека лезет не в те библиотеки, без симптома советует общее.
Промпт «почини бота, он не работает» — это ноль информации. Агент сгенерирует пять гипотез, ни одна не попадет в точку. Хороший дебаг-промпт занимает 5-7 строк и содержит четыре блока: стек, симптом, лог, желаемое поведение.
Базовый шаблон под Windsurf:
Стек: aiogram [версия], [Redis/Postgres/SQLite], [деплой VPS/Railway/Render]
Что должно происходить: [одно предложение]
Что реально происходит: [симптом]
Лог ошибки (если есть): [traceback или 'логи чистые']
Уже пробовал: [короткий список из 1-3 пунктов]
Задача:
1) найди корень проблемы
2) покажи минимальную правку файла
3) добавь логгирование чтобы похожий баг поймать раньше
С таким промптом Cascade или Composer выдают точечную правку, без переписывания половины файла. Если бот сложный и логику нужно понять с нуля, добавьте @codebase в начало промпта, агент сделает быстрый обзор архитектуры.
Для глубокого reasoning по архитектурным багам выгоднее Claude Opus 4.7. Для типовых исправлений в одном файле — Sonnet 4.6 или DeepSeek V4. Если бот для бизнеса с продакшен-трафиком и нужен системный аудит, проще записаться на консультацию к Максиму и пройти полную проверку за вечер.
FAQ по дебагу Telegram-ботов
Можно ли дебажить Telegram-бот без знания Python
Да. Windsurf и Cursor читают логи, объясняют ошибки и предлагают исправления текстом. Вы копируете traceback в чат с агентом, выбираете Claude Sonnet 4.6 или Opus 4.7 и получаете готовый патч. Понимание основ все же нужно, чтобы оценить корректность правки.
Почему бот работает локально, но падает на сервере
Чаще всего из-за переменных окружения. Локально подхватывается .env, на сервере переменные нужно прописать вручную через панель хостинга или systemd-юнит. Вторая причина: разная версия Python или библиотек. Зафиксируйте версии в requirements.txt.
Что выбрать новичку polling или webhook
Polling. Для локальной разработки и проектов до 1000 пользователей разница в скорости незаметна, а возни в десять раз меньше. Webhook стоит включать, когда телеграм бот для бизнеса выходит в продакшен на VPS с белым IP и HTTPS.
Как понять что виноват токен бота
В логах увидите Unauthorized или 401. Зайдите в @BotFather, нажмите /token, скопируйте заново и аккуратно вставьте. Невидимый пробел в начале или конце токена дает ровно ту же ошибку, что и совсем неверный токен.
Почему апдейты приходят с задержкой 30 секунд
Если предыдущий запрос вернул ошибку 500 или таймаут, Telegram ставит апдейт в очередь и шлет повторно с возрастающей задержкой. Починили баг, подождите минуту, очередь рассосется сама. Не нужно перезапускать бота каждые пять секунд.
Стоит ли писать чат-боты на aiogram 3 или остаться на 2
На aiogram 3. Версия 2 в режиме поддержки, новые фичи в нее не добавляются. Миграция занимает день, если бот небольшой. Магические фильтры и роутеры сильно упрощают код, особенно когда чат-бот для бизнеса разрастается до десятка сценариев.
Можно ли использовать Windsurf для дебага без оплаты
Бесплатный тариф Windsurf дает ограниченное количество premium-запросов в месяц. Для разовой починки бага хватает. Если дебажите боты регулярно, тариф Pro за 15 долларов в месяц окупается одним рабочим вечером.
Подобрали стек для своего бота, но застряли на одном из этих багов? Загляните в каталог AI IDE на VibeCoderz и обзор AI-агентов под задачи разработки. Если бот сложнее, чем кажется, и нужен внешний взгляд, запишитесь на консультацию к Максиму. Час разбора экономит обычно от двух до пяти вечеров самостоятельного дебага.
Обновлено: октябрь 2026. Команда VibeCoderz.
