---
title: Диагностика
weight: 1
---

**Цель:** выявить и устранить частые ошибки при разработке под Quetza.

## 1. Сбои при обнаружении модулей

**Симптом:** бот запускается, но модуль не подхватывается.
**Причина:** нарушена структура файлов или соглашения об именах.

{{% details title="Чек-лист: Структура директорий" closed="false" %}}

- [ ] Каталог модуля существует: `src/modules/<name>/`.
- [ ] Файл `module.ts` экспортирует переменную `name`.
- [ ] Каталог команд называется именно `commands/` (а не `cmds/`).
- [ ] Выполнена сборка `pnpm build` (Quetza работает из `dist/`).
      {{% /details %}}

## 2. Проблемы с регистрацией команд

**Симптом:** команда `/command` не появляется в Discord.

### Глобальная регистрация и регистрация на тестовом сервере

- **Глобальная регистрация:** команды, зарегистрированные глобально, могут обновляться до 1 часа и подпадают под жёсткие лимиты Discord по частоте запросов (rate limits).
- **Тестовый сервер (guild):** в режиме разработки Quetza публикует команды на указанном сервере мгновенно.
  - **Настройка:** проверьте, что в `.env` установлены переменные `NODE_ENV=development` и `DEV_GUILD_ID`.

### Лимиты частоты запросов (Rate Limits)

Частая повторная публикация глобальных команд приводит к превышению лимитов Discord. Для итеративной разработки всегда используйте тестовый сервер.

## 3. Ошибки взаимодействия (Interaction Failures)

**Симптом:** сообщение «Приложение не отвечает».
**Причина:** обработка команды длилась дольше 3 секунд без отложенного ответа (deferReply).

**Решение:**

```typescript
// ПЛОХО
await longRunningTask();
await interaction.reply('Готово'); // Слишком поздно!

// ХОРОШО
await interaction.deferReply();
await longRunningTask();
await interaction.editReply('Готово');
```

## 4. Утечки состояния

**Симптом:** потребление памяти растёт, данные перемешиваются между разными серверами.
**Причина:** состояние хранится глобально, а не изолированно для каждого сервера.

**Диагностика:**
Проверьте код контроллера:

- ❌ `private player: AudioPlayer;` (состояние общее для всех серверов)
- ✅ `private players = new Map<string, AudioPlayer>();` (состояние изолировано по ID сервера)

## 5. Обработка событий

**Симптом:** обработчик срабатывает несколько раз или не вызывается вовсе.

- **Срабатывает несколько раз:** слушатели событий суммируются. Проверьте, не зарегистрирован ли один и тот же обработчик в двух разных модулях.
- **Не срабатывает:** убедитесь, что обработчик корректно экспортирует `name` и `execute`.

> [!TIP]
> **Режим отладки (Debug Mode):**
> включите подробное логирование, чтобы видеть список всех модулей и команд, загружаемых на этапе старта бота.