FiveM: скриптовые ошибки в консоли сервера — как читать и исправлять

MAATRIX GAMES

Сервер запустился, но консоль сыпет красным текстом, а ресурс, который ты только что поставил, не работает — знакомая картина для любого, кто хоть раз собирал RP-сервер на FiveM. Проблема в том, что консоль FiveM выдаёт ошибки не всегда понятным языком: где-то это чистый Lua-трейс, где-то обёрнутая JS-ошибка, а где-то вообще молчаливый отказ ресурса стартовать без внятной причины. Разберём, как читать эти сообщения, быстро находить виновный ресурс и чинить самые частые причины — от опечатки в конфиге до конфликта версий ESX и QBCore.

Где смотреть ошибки и как включить подробный вывод

Основной источник — консоль сервера (txAdmin в веб-интерфейсе или чистый консольный вывод, если гоняешь FXServer напрямую через run.sh/FXServer.exe +exec server.cfg). Если у тебя txAdmin, вкладка Console показывает тот же поток, что и raw-консоль, плюс подсвечивает критические ошибки красным.

Первое, что стоит сделать при непонятной ошибке — не полагаться на память и перечитать вывод сверху вниз при старте: FiveM печатает построчно, какой ресурс стартует (Started resource X), и если следом идёт ошибка, она почти всегда относится именно к этому ресурсу. Если ошибка выскакивает не при старте, а во время игры (игрок что-то сделал и сервер упал в красный текст) — смотри временную метку и сопоставляй с действием игрока, это часто подсказывает контекст (например, ошибка вылезает только когда игрок садится в машину — значит, дело в vehicle-скрипте).

Полезно держать под рукой отдельный лог-файл, а не полагаться только на скроллбэк консоли — при перезапуске сервера история теряется. Если у тебя ещё не настроен сбор логов и разбор крашей системно, посмотри отдельный материал про логи и краш-репорты — принципы поиска причины там применимы и к FiveM.

Анатомия ошибки: Lua и JS-трейсы

Типичная Lua-ошибка выглядит так:

SCRIPT ERROR: @qb-vehiclekeys/server/main.lua:45: attempt to index a nil value (field 'Player')

Разбираем по частям:

• @qb-vehiclekeys — имя ресурса-виновника. Именно его надо открывать.
• server/main.lua:45 — файл и строка внутри ресурса.
• attempt to index a nil value (field 'Player') — суть ошибки: код пытается обратиться к полю Player у переменной, которая оказалась nil (то есть не была получена).

Самые частые типы Lua-ошибок и что они означают:

Почти всегда nil value в контексте фреймворка (ESX/QBCore) означает одно из двух: либо игрок ещё не успел авторизоваться (race condition при старте ресурса), либо экспорт из одного ресурса не совпадает с тем, что ждёт другой — обычно после обновления одного из модулей без обновления второго.

Часть ресурсов на FiveM пишется на JavaScript (через Node.js-рантайм FXServer) — трейс выглядит иначе, ближе к обычному Node: [script:my-resource] TypeError: Cannot read properties of undefined (reading 'source') at onNet (resource/server.js:12:20). Имя ресурса тут в квадратных скобках, но логика поиска причины та же — смотри файл и строку, смотри какое свойство читается у undefined. Частая причина в JS-ресурсах FiveM — обращение к source (ID игрока) вне контекста серверного события, например, если функция вызвана напрямую, а не через onNet/RegisterNetEvent.

"Failed to load script" и "Error running resource" — что это значит на самом деле

Это не runtime-ошибка, а ошибка загрузки — ресурс не смог даже стартовать. Причины почти всегда одни и те же:

• Синтаксическая ошибка в Lua/JS-файле — пропущенная скобка, кавычка, end. Консоль обычно указывает файл и строку прямо перед этим сообщением.
• Отсутствует или сломан fxmanifest.lua — проверь, что в нём указаны все нужные файлы (client_scripts, server_scripts, shared_scripts) и правильный fx_version/game 'gta5'.
• Несовместимая версия манифеста — если ресурс старый, в нём может быть __resource.lua вместо fxmanifest.lua, что на актуальных билдах FXServer (конец 2026 года это уже давно норма) либо не подхватывается, либо подхватывается с предупреждением.
• Ресурс зависит от другого ресурса, который не стартовал раньше него — самая частая причина в связке с фреймворками, разберём отдельно ниже.

Если видишь просто Error parsing script @resource/file.lua, открой файл на указанной строке — почти всегда там опечатка: незакрытая строка, лишняя запятая в таблице, then без end.

Как искать ресурс по имени из стектрейса

Имя ресурса в ошибке — это имя папки внутри resources/, а не отображаемое название мода. Если у тебя структура вроде:

resources/
  [qb]/
    qb-core/
    qb-vehiclekeys/
  [standalone]/
    my-custom-script/

то ошибка @qb-vehiclekeys/... ведёт в resources/[qb]/qb-vehiclekeys/. Быстро найти физический путь можно через find:

find resources/ -maxdepth 3 -iname "qb-vehiclekeys"

Если ошибка сыплется сразу пачкой при старте (десяток строк за один рестарт), не пытайся чинить всё сразу — найди самую первую ошибку в логе. Часто один упавший базовый ресурс (например, qb-core или es_extended) тянет за собой каскад ошибок во всех зависимых скриптах, и это выглядит как "всё сломалось", хотя причина одна.

Отдельно стоит проверить, не твой ли это самописный или скачанный скрипт — если ошибка в стороннем ресурсе с непонятным именем, стоит свериться с тем, как вообще правильно добавлять сторонний код на сервер, это разобрано в статье про установку кастомных скриптов на FiveM.

Порядок запуска ресурсов в server.cfg и почему он важен

FiveM запускает ресурсы строго в том порядке, в котором они перечислены ensure/start в server.cfg — сверху вниз. Если ресурс B зависит от экспортов или таблиц ресурса A, а в конфиге он идёт раньше A — при старте B ты почти гарантированно получишь attempt to index a nil value, потому что нужный ресурс ещё не успел загрузиться.

Правильный порядок для типичного QBCore-сервера выглядит примерно так:

# 1. Основа
ensure qb-core

# 2. Библиотеки/хелперы, от которых зависит остальное
ensure qb-menu
ensure qb-input
ensure qb-target

# 3. Экономика и данные (нужны почти всем скриптам)
ensure oxmysql
ensure qb-inventory

# 4. Игровые системы поверх базы
ensure qb-vehiclekeys
ensure qb-garages

# 5. Кастомные и косметические ресурсы — в конце
ensure my-custom-script

Если сомневаешься в порядке для конкретного ресурса — открой его fxmanifest.lua и посмотри секцию dependencies или server_scripts — многие авторы явно указывают, что должно быть загружено раньше через dependency 'имя-ресурса'. Также стоит проверить dependencies { 'qb-core' } — если она есть, но qb-core не подключён вообще или подключён ниже по списку, FXServer выдаст явное предупреждение о недостающей зависимости ещё до попытки старта самого ресурса.

Ещё одна деталь: ensure перезапускает ресурс, если он уже был запущен (полезно при разработке), а start просто стартует, если ещё не запущен — для production-конфига разницы почти нет, но при живой отладке ensure resource_name в консоли сервера — быстрый способ перезагрузить один скрипт без рестарта всего сервера.

Конфликт версий фреймворка: ESX и QBCore

Большинство скриптовых ошибок на готовых RP-сборках — это не баг самого скрипта, а рассинхрон версий. Типичные сценарии:

Смешение легаси и актуальных функций ESX. Старые скрипты, написанные под ESX Legacy, используют ESX.GetPlayerFromId(source), тогда как некоторые более новые сборки ждут ESX.GetPlayerFromIdentifier или другую сигнатуру callback'ов (ESX.TriggerServerCallback вместо колбэков через RegisterServerEvent). Если скачал скрипт с гитхаба без указания версии фреймворка — сверяй, под какую ветку ESX (legacy/new) он писался, это обычно указано в README репозитория.

QBCore: QBCore.Functions.GetPlayer(source) возвращает nil. Классика — вызов идёт до того, как qb-core успел зарегистрировать игрока в PlayerData, либо игрок ещё физически не заспавнился (событие playerSpawned ещё не сработало). Решается оборачиванием обращения к игроку в проверку:

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end

Смешивание ESX- и QBCore-специфичных скриптов на одном сервере. Это не поддерживается "из коробки" — ресурсы под один фреймворк почти всегда обращаются к глобальным объектам (ESX или QBCore) напрямую, и если сервер поднят на другом фреймворке, такой ресурс просто упадёт с ошибкой attempt to index a nil value (global 'QBCore') или аналогичной. Бывают адаптеры-мосты (bridge-ресурсы), которые эмулируют один API поверх другого, но это дополнительная точка отказа — если стоит такой мост, ошибку стоит искать сначала в нём. Подробное сравнение самих фреймворков и что переносится между ними без боли — в статье ESX и QBCore: сравнение фреймворков.

Ошибки, связанные с картами и MLO

Если ошибка вылезает после установки кастомной карты или интерьера (MLO), она обычно выглядит иначе — не Lua runtime error, а сообщение об отсутствующих моделях в консоли клиента (Failed to load model или предупреждения streaming-системы), либо сервер вообще не ругается, но у игроков вылеты при заходе в конкретную зону. Это нередко путают со скриптовыми ошибками, хотя причина в ассетах — неправильный data_file в манифесте, отсутствующий .ytyp/.ymap, или превышен лимит стриминга. Если разбираешься именно с картами и MLO — это отдельная тема, разобранная в статье про карты и MLO для FiveM-сервера.

Практический чек-лист диагностики

Когда видишь ошибку и не знаешь, с чего начать — иди по порядку:

1. Найди имя ресурса в квадратных или собачьих скобках трейса.
2. Проверь, это ошибка загрузки или runtime — до Started resource или после.
3. Открой файл на указанной строке — половина ошибок это опечатки, лишний символ, незакрытый блок.
4. Проверь порядок в server.cfg — зависимость идёт раньше или позже нужного ресурса.
5. Сверь версию фреймворка — не смешаны ли ESX/QBCore вызовы или легаси/новый API.
6. Перезапусти только проблемный ресурс (restart имя_ресурса в консоли) вместо полного рестарта — быстрее проверяешь гипотезу.
7. Если ошибка появляется только у части игроков — проверь их клиентские моды/стримы, возможно проблема не в скрипте, а в рассинхроне ассетов.

Держи под рукой список ресурсов, которые ты менял последними — в 80% случаев виновник это последний добавленный или обновлённый скрипт, а не что-то, что "само сломалось".

Частые вопросы