Почему плагин не грузится: 10 ошибок в конфигах YAML

Поставили плагин, перезапустили сервер, а команды нет. Или плагин работал, вы поправили одну строчку в конфиге, и он перестал отвечать. Чаще всего виноват не плагин, а один символ в config.yml. Ниже порядок поиска и ошибки, которые попадаются раз за разом.

Сначала понять, что именно не загрузилось

Это два разных случая, и лечатся они по-разному.

• Не загрузился сам jar. В консоли при старте строка вроде Could not load 'plugins/Имя.jar'. Конфиг тут почти никогда ни при чём: плагин собран под другую версию игры или Java, не хватает зависимости вроде Vault или ProtocolLib, в папке лежат две копии одного плагина. Про установку плагинов есть отдельная статья.
• Плагин загрузился, но конфиг не прочитан. В логе ошибка с именем файла и словами InvalidConfigurationException, YAML или SnakeYAML. Плагин работает на настройках по умолчанию, отключается сам или падает на первой команде. Это наш случай.

Как найти строку с ошибкой

1. Откройте logs/latest.log. В нём весь запуск с первой строки, а консоль хостинга часто показывает только хвост.
2. Найдите имя плагина и первую ошибку после него. Всё, что ниже, обычно следствие первой.
3. В тексте ошибки есть line и column: строка и позиция, где парсер сдался. Сама ошибка часто на строку-две выше.
4. Откройте файл в редакторе, который подсвечивает YAML и показывает пробелы: VS Code, Notepad++. Обычный Блокнот табуляцию не отличает от пробелов.
5. Проверьте файл до перезапуска. На Linux табуляции ищет grep, а если стоит Python с PyYAML, он прочитает файл целиком и назовёт ошибку.
6. Перезапустите сервер или выполните перезагрузку самого плагина, если у него есть такая команда. /reload всего сервера не используйте.

grep -nP '\t' plugins/Имя/config.yml
python3 -c "import yaml; yaml.safe_load(open('plugins/Имя/config.yml', encoding='utf-8'))"

Вторая команда молчит, если синтаксис цел. Если нет, напишет, на какой строке беда.

10 ошибок, которые ломают конфиг

1. Табуляция вместо пробелов

YAML принимает для отступов только пробелы. Один таб, и файл не читается целиком. Ошибка узнаётся сразу:

found character '\t(TAB)' that cannot start any token. (Do not use \t(TAB) for indentation)

Замените табы на пробелы и включите в редакторе вставку пробелов по клавише Tab.

2. Сбитый отступ

Отступ определяет, какому разделу принадлежит ключ. Сдвинули строку на два пробела влево, и она уехала в соседний раздел. Хуже всего то, что ошибки часто нет: файл валиден, просто плагин ищет настройку в другом месте.

# плохо: radius оказался в settings, а не в spawn
settings:
  spawn:
    world: world
  radius: 50

# хорошо
settings:
  spawn:
    world: world
    radius: 50

3. Нет пробела после двоеточия

radius:50 для YAML не ключ со значением, а одна строка текста. Рядом с нормальными ключами это даёт ошибку could not find expected ':', а в одиночку молча превращает раздел в строку. Правило простое: после двоеточия ключа всегда пробел.

4. Двоеточие внутри текста

Сообщение вроде restart: Внимание: перезагрузка через минуту ломает файл с ошибкой mapping values are not allowed here. Второе двоеточие с пробелом YAML считает началом нового ключа. Лечится кавычками:

restart: '&cВнимание: перезагрузка через минуту'

5. Цвет с решёткой

Решётка после пробела начинает комментарий. color: #FFAA00 читается как пустое значение, а сам цвет становится комментарием. Ошибки в логе не будет, просто цвет не применится. Всё, что начинается с #, берите в кавычки: color: '#FFAA00'.

6. Спецсимвол в начале значения

Ряд символов в начале значения YAML понимает по-своему: & это якорь, * ссылка, ! тип, [ и { начало списка и словаря, а % и @ вообще не могут начинать текст без кавычек. Для серверов это больная тема, потому что цветовые коды начинаются с &, а плейсхолдеры с %.

# плохо
prefix: &c[Админ]
format: %player_name% зашёл
tag: [VIP] Вася

# хорошо
prefix: '&c[Админ] '
format: '%player_name% зашёл'
tag: '[VIP] Вася'

7. Кавычки внутри кавычек

В одинарных кавычках апостроф удваивается: 'You don''t have permission'. В двойных кавычках обратная косая черта служит экраном, поэтому "C:\server" даст ошибку found unknown escape character. Для путей и текста с косой чертой берите одинарные кавычки.

8. Строка вместо списка

Описание предмета, список команд или миров плагин ждёт списком. Если написать одной строкой, он либо проигнорирует её, либо упадёт при открытии меню.

# плохо
lore: '&7Редкий меч'

# хорошо
lore:
  - '&7Редкий меч'
  - '&7Урон +5'

Пустой список пишется как [], а не пустым местом. И после дефиса тоже нужен пробел.

9. Числа, версии и «да/нет»

Загрузчик Bukkit по старым правилам YAML превращает yes, no, on и off в логические значения, а 1.20 в число 1.2. Если плагин ждёт текст, ответ викторины no станет false, а версия потеряет ноль. Такие значения тоже в кавычки: version: '1.20'.

10. Кодировка и невидимые символы

Файл, сохранённый не в UTF-8, превращает русский текст в кракозябры. Текст, скопированный из мессенджера или с сайта, иногда приносит неразрывные пробелы. Глазами отступ ровный, а для парсера это не пробел, и ключ получает лишний символ в имени. Сохраняйте в UTF-8 и перебивайте отступы руками, если строка пришла из чата.

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

• Правят не тот файл. У плагина бывают config.yml, messages.yml, папка с языками. После обновления рядом может лежать старая копия конфига с другим именем.
• Ключ переименован в новой версии. Синтаксис цел, но настройка не работает. Сверьтесь с конфигом по умолчанию: переименуйте свой, дайте плагину создать чистый и перенесите значения.
• Правка на включённом сервере. Часть плагинов сохраняет конфиг при выключении и затирает вашу правку старым содержимым из памяти.
• Один ключ дважды. Два раздела settings: в одном файле. В зависимости от загрузчика победит последний или файл не прочитается вовсе.
• Нет копии до правки. Сломали так, что уже не помните, как было. Перед правкой копируйте файл рядом.

Как то же сделать быстрее

В Cloud Panel настройки девяти популярных плагинов открываются формой с русскими подписями: Citizens, DecentHolograms, DeluxeMenus, Essentials, ItemsAdder, LuckPerms, MythicMobs, TAB и WorldGuard. Вы меняете значение в поле, а панель записывает в файл только его. Отступы, комментарии и остальные строки остаются байт в байт, так что табуляции и сбитому отступу взяться неоткуда.

Каждая правка попадает в журнал, любую можно откатить. Консоль, файлы и перезапуск сервера в том же окне. Если плагина нет в списке или файл уже сломан ручной правкой, чинить его придётся по шагам выше: за вас ошибку панель не угадает.

Чек-лист

1. В latest.log найдены файл, строка и столбец первой ошибки.
2. В файле нет табуляций.
3. Отступы одинаковые, вложенные ключи стоят под своим разделом.
4. После каждого двоеточия ключа есть пробел.
5. Значения с :, #, &, %, @, [ в кавычках.
6. Версии и слова yes, no, on, off в кавычках, если это текст.
7. Списки записаны списками.
8. Файл сохранён в UTF-8.
9. Копия файла сделана до правки.
10. После перезапуска в консоли нет ошибок этого плагина.

Править конфиги формой и откатывать одной кнопкой можно на своём сервере: 3 дня бесплатно.