Discord-бот не видит участников сервера: intents, кеш и загрузка members

Если Discord-бот подключен к серверу, отвечает на команды, но не видит участников, проблема обычно связана не с токеном. Нужно проверить Guild Members Intent, набор intents в коде, способ получения участников, кеш библиотеки и область OAuth-установки приложения.

Discord не обязан заранее передавать боту полный список участников. Для крупных серверов и некоторых сценариев данные нужно запрашивать явно, а привилегированный intent — включить одновременно в Developer Portal и в коде клиента.

Как проявляется проблема

• Список guild.members пустой или содержит только самого бота.
• Поиск пользователя по имени работает только после его сообщения в чате.
• События входа и выхода участников не приходят.
• Команда назначения роли сообщает, что участник не найден, хотя он есть на сервере.
• На маленьком тестовом сервере код работает, а на крупном — возвращает неполные данные.

Что такое Guild Members Intent

Guild Members Intent относится к привилегированным gateway intents. Он нужен для событий о присоединении, выходе и обновлении участников, а также для полноценной загрузки member-данных через gateway. Одного переключателя в панели недостаточно: библиотека должна запросить этот intent при подключении.

• В Developer Portal откройте приложение, затем раздел Bot и Privileged Gateway Intents.
• Включите Server Members Intent, если функции бота действительно требуют данных участников.
• Добавьте соответствующий intent в конфигурацию клиента вашей библиотеки.
• Перезапустите процесс: действующее gateway-соединение не изменит intents само.

Проверьте intents в коде

Названия зависят от библиотеки и версии: GuildMembers, GUILD_MEMBERS или аналогичное значение. После крупных обновлений discord.js, discord.py и других SDK формат конфигурации мог измениться.

• Выведите безопасный список запрошенных intents при запуске.
• Проверьте документацию именно установленной версии библиотеки.
• Убедитесь, что не создается второй Client с сокращенным набором intents.
• Посмотрите gateway close code: Discord может закрыть соединение при запрещенном intent.

Кеш участников не равен полному списку

Коллекция members в памяти обычно является кешем, а не гарантированно полным каталогом. Она может содержать только участников, которых библиотека уже получила через события, команды или явные запросы.

• Не используйте размер кеша как точное число участников сервера.
• Для одного известного пользователя запрашивайте member по стабильному Discord user id.
• Для массовой операции используйте штатный fetch или chunking библиотеки и учитывайте ограничения.
• Не ищите пользователя только по display name: имена могут совпадать и изменяться.

Проверьте OAuth-установку и сервер

Бот должен быть установлен именно в тот guild, данные которого запрашивает код. Ошибка часто возникает, когда в конфигурации остался id тестового сервера или приложение было переустановлено с другой ссылкой.

• Сверьте application id, bot user id и guild id в событии ready.
• Проверьте, что команда выполняется в ожидаемом guild, а не в личном сообщении.
• Для slash-команд проверьте корректные scopes bot и applications.commands.
• После изменения установки не используйте старые жестко записанные channel и guild id.

Нужны ли боту права администратора

Для чтения member-данных не следует автоматически выдавать Administrator. Intents управляют тем, какие события и данные доступны через gateway, а права сервера — какие действия бот может выполнять. Это разные уровни.

• Выдайте только права, необходимые конкретным командам.
• Для назначения ролей проверьте иерархию ролей: роль бота должна находиться выше целевой.
• Для доступа к закрытым каналам отдельно проверьте channel overwrites.
• Не маскируйте ошибку отсутствующего intent выдачей полного Administrator.

Пошаговая диагностика

• Подтвердите, что бот получает ready и видит нужный guild.
• Запишите версию Discord-библиотеки и фактический набор intents.
• Проверьте Server Members Intent в Developer Portal.
• Перезапустите единственный экземпляр бота и посмотрите gateway ошибки.
• Запросите одного участника по user id через штатный API библиотеки.
• Сравните результат прямого fetch и содержимое локального кеша.
• Для полного списка проверьте chunking, pagination, rate limits и завершение загрузки.
• Отдельно протестируйте события присоединения, выхода и обновления участника.

Как исправить

• Включите привилегированный intent только при реальной необходимости функций бота.
• Запросите тот же intent при создании клиента и полностью перезапустите процесс.
• Замените поиск по имени на работу со стабильным user id.
• Для единичных операций используйте прямой fetch вместо предположения, что кеш полный.
• Для массовых задач загружайте участников контролируемо и обрабатывайте rate limit.
• Не храните полный список бесконечно: обновляйте данные событиями или по сроку актуальности.

Если сервер крупный

Для верифицированных приложений Discord может требовать отдельное одобрение привилегированного intent. На крупных серверах нельзя рассчитывать, что весь список мгновенно появится в памяти после ready.

• Проверьте статус privileged intent для приложения в Developer Portal.
• Не запускайте тяжелую обработку списка до завершения штатной загрузки.
• Разделяйте единичный поиск участника и массовую синхронизацию.
• Храните checkpoint массовой задачи и не повторяйте обработку уже завершенных страниц.

Как проверить результат

• Бот находит контрольного участника по user id без предварительного сообщения в чат.
• Событие нового участника приходит один раз и содержит ожидаемый guild id.
• Выход участника корректно обновляет локальные данные.
• На крупном сервере загрузка завершается без timeout и бесконечных повторов.
• После рестарта бот не зависит от случайно сохранившегося кеша предыдущего процесса.
• Команды не получают лишние административные права.

Типичные ошибки

• Включить intent в панели, но забыть добавить его при создании клиента.
• Добавить intent в код, но не включить его в Developer Portal.
• Считать guild.members полным списком сразу после ready.
• Искать пользователя по отображаемому имени вместо id.
• Запрашивать весь сервер для каждой команды и быстро получать rate limit.
• Выдать Administrator, хотя проблема находится в gateway intents.
• Запустить несколько экземпляров бота с разной конфигурацией и сравнивать их кеши.

Как не допустить повторения

• Зафиксируйте intents и версии библиотеки в конфигурации проекта.
• Добавьте smoke test поиска контрольного участника после запуска.
• Логируйте guild id, user id, тип операции и результат без токена и личных данных.
• Мониторьте gateway disconnect, rate limit и ошибки массовой загрузки.
• Проверяйте привилегированные intents после переноса приложения или обновления SDK.

Итог

Если Discord-бот не видит участников, сначала проверьте Guild Members Intent в двух местах: Developer Portal и коде клиента. Затем отделите локальный кеш от прямого API-запроса и убедитесь, что бот работает с правильным guild и стабильными user id.

Если проблема остается, я могу проверить конфигурацию Discord-приложения, intents, версию библиотеки и логи gateway, затем исправить загрузку участников без выдачи боту лишних прав.