Очень подробный Troubleshooting для NextLib 1.0.8: диагностика по симптомам, root-cause анализ, fix-плейбуки и профилактика инцидентов.

Troubleshooting

Эта страница построена как инженерный playbook: вы берёте симптом, проходите диагностику по шагам и быстро выходите на рабочее решение.

Как эффективно дебажить NextLib

Перед любым «хаотичным фиксингом»:

Снимите первый stacktrace (не последний warning).
Зафиксируйте версию библиотеки (1.0.8).
Проверьте sequence инициализации (onEnable порядок).
Локализуйте модуль: DB / GUI / Reload / i18n / Quests.

Главная ошибка при дебаге: чинить симптомы, не найдя root cause.

A. Dynamic Database проблемы

A1. `Missing JDBC driver for ...`

Симптом:

при DatabaseManager.register(...) падает ConfigurationException.

Диагностика:

Проверить зависимости сборки (sqlite/postgres/mysql driver).
Проверить runtime jar на сервере (driver реально внутри или доступен отдельно).
Если shading/minimization — убедиться, что драйвер не вырезан.

Исправление:

добавить корректный драйвер;
пересобрать и задеплоить.

Профилактика:

хранить «матрицу БД -> драйвер» прямо в docs проекта.

A2. `Failed to configure HikariCP pool ...`

Симптом:

ошибка при старте пула.

Причины:

неверный host/port/database;
неверные креды;
некорректные свойства Hikari (maximumPoolSize, connectionTimeout и т.д.);
сеть/фаервол.

Диагностика:

Проверить ручное подключение к БД.
Упростить конфиг до минимального рабочего.
Добавлять свойства пула по одному.

A3. `Failed to resolve constructor` / маппинг сущности сломан

Симптом:

запрос выполняется, но сущность не создаётся.

Проверить:

Конструктор покрывает все поля.
Порядок параметров соответствует полям.
Типы совпадают (Integer vs Long vs String).

A4. `Unknown field ...` в where/set

Симптом:

fluent запрос падает на этапе сборки.

Причина:

имя поля не из Java-сущности.

Паттерн решения:

вынести имена полей в константы;
не использовать «магические строки» по всему коду.

A5. Запросы стали медленными

Симптомы:

команды с БД тормозят;
spikes в latency.

Быстрый план:

Добавить таймер-метрики вокруг запросов.
Проверить индексы по where полям.
Добавить take(...) на большие выборки.
Проверить размер пула.

Если не помогло:

снять explain plan в СУБД;
вынести тяжёлые чтения в специализированные SQL.

A6. `skip(offset) requires take(limit)`

Симптом:

исключение при пагинации.

Fix:

findMany().take(20).skip(40).execute();

B. GUI API проблемы

B1. `GUI '<id>' not found!`

Причины:

меню не загружено;
id не совпадает с именем файла;
openGui вызван до loadFromFolder.

Чек:

Есть ли файл menus/main.yml.
Вызывается ли loadFromFolder в onEnable.
Открываете ли вы openGui(player, "main").

B2. Клики не работают

Чаще всего:

использованы неверные YAML ключи (onLeftClick вместо on_left_click).

Проверить:

on_left_click
on_right_click
enchanted_when

B3. `Unknown GUI action ...`

Опечатка в action.
Кастомное действие не зарегистрировано.

Fix:

Actions.registerAction("my_action", (manager, args) -> player -> { /* ... */ });

B4. Item пропал из меню

Причины:

слот вне диапазона size;
некорректный диапазон в slots;
неверный material.

Проверка:

серверный лог при загрузке GUI содержит warning с конкретным item key.

B5. Reload GUI не отражает изменения

Причины:

reload вызывается не в том менеджере;
YAML правится не в той папке;
кэш/старый файл на сервере.

Fix:

проверить loadFromFolder путь;
вызвать guiManager.reloadAll();
убедиться, что игроки переоткрывают меню.

C. Command API проблемы

C1. Команда не зарегистрировалась

Проверить:

Есть ли команда в plugin.yml.
Совпадает ли имя в registerCommand.
Выполняется ли этот код в onEnable.

C2. Всегда `No permission`

Проверить:

правильность permission string,
права пользователя/группы,
permission message команды.

C3. `IndexOutOfBoundsException` на args

Причина:

нет проверки длины args.

Стандарт:

if (args.length < required) {
  sender.sendMessage("Usage: ...");
  return;
}

D. Validation API проблемы

D1. Ошибки валидации «теряются»

Причина:

early throw на первой ошибке.

Решение:

собирать общий ValidationResult,
бросать исключение только в конце.

D2. Невозможно локализовать ошибки

Причина:

нестабильные code (err1, x).

Решение:

стабильные коды: not_blank, max_length, range.

E. Reload API проблемы

E1. `reloadAll` проходит, но часть состояния старая

Причины:

не все подсистемы зарегистрированы в ReloadManager;
reload метод обновляет только часть полей.

Плейбук:

Выписать все подсистемы.
Для каждой сделать Reloadable.
Проверить идемпотентность reload.

E2. Reload ломает систему

Причина:

модуль переключает состояние неатомарно.

Решение:

строить новый state отдельно,
только после успешной подготовки заменять старый.

F. Observability API проблемы

F1. Метрики «неинформативны»

Причина:

плохие имена ключей,
нет таймеров вокруг hot path.

Решение:

использовать стабильные module.action.metric ключи;
измерять DB/commands/reload.

F2. Слишком много шума в логах

Решение:

структурированные события только для важных этапов;
уровень debug включать точечно.

G. Quests API проблемы

G1. `Unknown quest id`

Причина:

quest definition не зарегистрирован.

Fix:

G2. Прогресс не сохраняется

Проверить:

Используется ли QuestStore.
Нет ли исключений в сохранении.
Вызывается ли восстановление при логине (restorePlayer).

G3. Прогресс не растёт

Причины:

не тот objective type;
matches...() не матчит payload;
event amount передаётся 0.

H. i18n проблемы

H1. Вместо сообщения ключ

Причины:

нет ключа в locale;
нет ключа в fallback locale.

Fix:

добавить ключ в локали;
сделать reload переводов.

H2. Локаль не подхватывается

Проверить имена файлов: ru_RU.properties, en_US.properties.

I. CI/CD и деплой

I1. Netlify: секреты найдены в репозитории

Симптом:

Build падает на secrets scanning.

Fix варианты:

убрать чувствительные значения из кода/README;
для false positive использовать omit-правила в Netlify.

I2. Vercel internal deploy error после успешной сборки

Причина:

сбой платформы/инфраструктуры.

Решение:

redeploy;
проверить status provider;
открыть тикет с deployment id.

J. Универсальный дебаг-плейбук (10 минут)

Скопировать первый stacktrace.
Определить модуль, где ошибка.
Проверить инициализацию и конфиг.
Проверить версии и зависимости.
Прогнать минимальный воспроизводимый сценарий.

K. Профилактика инцидентов

Единый startup-checklist.
Health checks на БД/локаль/GUI.
Таймеры на медленные операции.
Структурированные логи ключевых действий.
Регулярный smoke test после каждого релиза.

Если следовать этой странице как процедуре, большинство проблем находится быстро и воспроизводимо, без «угадываний».