Ниже — упорядоченный чеклист и набор конкретных шагов/команд, которые помогут найти и исправить причину, по которой Telegram‑бот не запускается. Работайте сверху вниз — часто проблема обнаруживается на первых пунктах.
1) Воспроизведите и зафиксируйте ошибку
- Запустите скрипт вручную в консоли: python your_bot.py — посмотрите стек‑трэйс и сообщения об ошибке.
- Если бот запускается как служба/контейнер — посмотрите логи службы (systemd, docker, pm2 и т.п.).
Команды:
- systemctl status your-service && journalctl -u your-service -n 200
- docker logs <container> --tail 200
2) Проверка токена и доступа к API
- Убедитесь, что в конфигурации/переменных окружения стоит правильный токен от BotFather.
- Протестируйте токен ручным запросом:
https://api.telegram.org/bot<TOKEN>/getMe
или в консоли: curl -s https://api.telegram.org/bot<TOKEN>/getMe | jq .
- Если getMe возвращает ошибку (401 Unauthorized) — токен неверный или отозван. Получите новый у BotFather.
3) Polling vs Webhook — проверьте подход и конфликт
- Если вы используете long polling (getUpdates):
- Убедитесь, что нигде не стоит webhook для этого бота. Если webhook установлен, getUpdates не будет выдавать обновления.
- Для удаления webhook: https://api.telegram.org/bot<TOKEN>/setWebhook?url= (пустой url).
- Если вы используете webhook:
- Проверьте getWebhookInfo: https://api.telegram.org/bot<TOKEN>/getWebhookInfo — посмотрите last_error_message/last_error_date.
- Убедитесь, что URL доступен по HTTPS и у вас валидный сертификат (Let's Encrypt и т.п.).
- Проверьте, что порт открыт и запросы доходят до приложения.
4) Тест минимальным скриптом
- Это быстро покажет, проблема в окружении или в коде:
Пример простого запроса (curl/Python):
- curl -s https://api.telegram.org/bot<TOKEN>/getMe
- Python:
import requests
print(requests.get(f'https://api.telegram.org/bot{TOKEN}/getMe').json())
- Если этот тест успешен, значит Telegram доступен и токен валиден — проблема в коде бота.
5) Посмотрите логи приложения и включите подробный логгинг
- Включите logging.DEBUG в вашей библиотеке/скрипте (python-telegram-bot, aiogram и т.д.).
- Обработайте исключения при инициализации (try/except вокруг кода запуска) и логируйте stacktrace.
- Убедитесь, что приложение не падает при импорте модулей (ошибки зависимостей, синтаксис).
6) Проверка зависимостей и окружения
- Убедитесь, что установлены нужные библиотеки и версии Python:
- python -V ; pip freeze
- Если используете виртуальное окружение — активируйте его при запуске службы/контейнера.
- При миграции между версиями библиотек (например, python-telegram-bot v13 → v20) API запуска мог измениться — проверьте пример кода для вашей версии.
7) Сеть, файервол и хостинг
- Проверьте, что наружные соединения к api.telegram.org разрешены.
- Для webhook: проверьте, что порт 443 (или выбранный) открыт, сертификат корректен.
- Команды:
- ss -tlnp | grep :443
- sudo ufw status
- sudo iptables -L -n
- openssl s_client -connect yourdomain:443 -servername yourdomain
8) Если бот запущен, но не получает сообщения
- Проверьте, не заблокировал ли бот юзер или не удалён ли бот.
- Для polling: убедитесь, что другой процесс не держит getUpdates (одновременное polling с тем же токеном конфликтует).
- Проверьте права бота в группах (privacy mode), если сообщения не доходят из групп.
9) Контейнеры/CI/CD/серверные службы
- Посмотрите логи контейнера, переменные окружения внутри контейнера.
- Убедитесь, что команда запуска в Dockerfile/entrypoint корректна.
- В systemd unit файле путь до python/venv и рабочая директория указаны правильно.
10) Частые и типовые ошибки и способы их решения
- 401 Unauthorized → неправильный токен → заменить токен.
- getUpdates пусто, хотя есть сообщения → webhook установлен → удалить webhook или использовать webhook‑сервер.
- Ошибки SSL при webhook → поставить валидный сертификат или использовать reverse proxy с HTTPS.
- Приложение падает сразу при старте → посмотреть stacktrace, исправить ошибку импорта или конфигурации.
- Rate limit / Too many requests → снизить частоту запросов, добавить задержки/retry.
- Ошибка "address already in use" → порт занят другим процессом — сменить порт или остановить процесс.
11) Последние шаги — локализация и исправление
- Сузьте проблему: переставьте блоки кода, отключите плагины/handlers, запустите минимальный бот, затем добавляйте функциональность по одному шагу, пока не появится ошибка.
- Если после всех проверок не ясно, где проблема — скопируйте минимальный рабочий лог и стек‑трэйс и покажите (я помогу проанализировать).
Если пришлёте:
- вывод getMe и getWebhookInfo,
- стек‑трэйс ошибки при запуске,
- команду/метод запуска (polling или webhook),
я подскажу конкретно, где смотреть и как исправить.