Ошибка «файл описания модуля module root не найден» появляется при установке или обновлении модуля, когда система не может прочитать служебный файл в корневой папке модуля — чаще всего из-за битого архива, неверной структуры каталогов или отсутствия прав на чтение. Типичный сценарий: администратор загружает модуль через панель управления CMS или распаковывает его вручную, а установщик останавливается с этим сообщением ещё до начала копирования файлов.
Такая ошибка встречается в системах управления сайтом, где каждый модуль обязан содержать файл описания — например, install/index.php с классом-описанием в 1С-Битрикс или аналогичный манифест в других CMS. Ниже разберём, что именно проверяет установщик, почему файл может «потеряться» и как восстановить структуру модуля без риска для работающего сайта.
Что означает эта ошибка
Любой модуль в модульной CMS — это не просто набор скриптов, а строго организованная папка. В её корне должен лежать файл описания модуля: он сообщает системе название, версию, зависимости и порядок установки. Установщик первым делом ищет именно этот файл, и если его нет по ожидаемому пути, процесс прерывается.
Сообщение вида «module root не найден» указывает, что система добралась до каталога модуля, но не обнаружила в нём обязательный манифест. Важно понимать: ошибка говорит о проблеме со структурой или доступом, а не о неисправности самой CMS. Поэтому переустанавливать движок сайта из-за неё не нужно.
Точное имя файла описания зависит от платформы: в 1С-Битрикс это install/index.php с классом, имя которого совпадает с идентификатором модуля, в других системах — XML- или JSON-манифест. Сверьтесь с документацией вашей CMS, чтобы знать, какой именно файл ищет установщик.
Основные причины появления ошибки
Прежде чем что-то исправлять, определите, на каком этапе файл описания был утерян. Практика показывает несколько типовых сценариев.
- 📦 Неполная распаковка архива — архив модуля скачан с обрывом или распакован с ошибками, часть файлов отсутствует.
- 📁 Лишний уровень вложенности — модуль распакован в папку вида
module/module/, и установщик смотрит не в тот каталог. - 🔒 Права доступа — файл описания существует, но веб-сервер не может его прочитать из-за ограничений прав.
- ✏️ Ручное редактирование — файл описания был переименован, перемещён или повреждён при правках.
- 🧩 Несовместимая версия — модуль собран под другую версию CMS, и структура его манифеста не распознаётся.
⚠️ Внимание: не копируйте файлы модуля поверх рабочего сайта «методом проб», пока не убедитесь, что архив целый и предназначен именно для вашей версии CMS. Повреждённый модуль может нарушить работу административного раздела.
Шаг 1. Проверка целостности архива модуля
Начните с источника. Скачайте дистрибутив модуля заново — из официального репозитория, маркетплейса CMS или личного кабинета разработчика. Если файл скачивался через нестабильное соединение, велика вероятность, что архив оборвался, и часть содержимого просто не записалась.
Распакуйте архив на локальном компьютере и убедитесь, что в корневой папке модуля присутствует файл описания и служебные каталоги. Если при распаковке архиватор сообщает об ошибках — дистрибутив повреждён, и устанавливать его бессмысленно.
Шаг 2. Проверка структуры каталогов
Вторая по частоте причина — неверная вложенность. При ручной распаковке на сервер легко получить путь вида /modules/mymodule/mymodule/install/index.php, тогда как установщик ищет файл описания на уровень выше. Откройте папку модуля на сервере и сравните её структуру с требованиями документации.
Для 1С-Битрикс ориентир такой: в каталоге модуля должна лежать папка install, а внутри неё — файл index.php с классом описания. Дополнительно проверьте, что идентификатор модуля в имени папки совпадает с именем класса в файле описания: расхождение тоже приводит к тому, что модуль «не виден» системе.
/modules/идентификатор_модуля/
install/
index.php ← файл описания модуля
version.php
...
☑️ Проверка структуры модуля перед установкой
Шаг 3. Права доступа и владелец файлов
Если файл описания на месте, а ошибка остаётся, проверьте, может ли веб-сервер его прочитать. При загрузке файлов по FTP или SSH под другим пользователем права могут оказаться такими, что процесс веб-сервера не получает доступ на чтение.
Конкретные значения прав зависят от настроек хостинга, поэтому сверьтесь с рекомендациями вашего хостинг-провайдера и документацией CMS. Общий безопасный принцип: каталоги должны быть доступны для чтения и выполнения, файлы — для чтения, а владельцем файлов должен быть пользователь, под которым работает веб-сервер или который указан в требованиях хостинга. Не назначайте всем файлам права 777 «для проверки» — это создаёт уязвимость.
Шаг 4. Совместимость версий и повторная установка
Модуль, собранный под другую версию CMS, может иметь иную структуру манифеста. Проверьте в описании дистрибутива, для каких версий платформы он предназначен, и сравните с версией вашей системы — она обычно указана в административной панели. Если модуль устарел, поищите актуальную сборку у разработчика.
После всех проверок выполните установку заново: удалите папку модуля, загрузите свежую копию, очистите кеш CMS, если платформа его использует, и повторите процедуру через штатный установщик. Ручное создание «пустого» файла описания, чтобы обмануть установщик, недопустимо — модуль без корректного манифеста установится с ошибками и может нарушить работу сайта.
⚠️ Внимание: перед любыми действиями с файлами на рабочем сайте сделайте резервную копию файлов и базы данных. Это позволит откатить изменения, если установка модуля пройдёт некорректно.
Сводная таблица: симптомы и действия
| Симптом | Вероятная причина | Действие |
|---|---|---|
| Ошибка сразу после загрузки архива | Битый или неполный дистрибутив | Скачать модуль заново из официального источника |
| Файл описания есть, но не находится | Лишний уровень вложенности папок | Выровнять структуру каталогов по документации |
| Ошибка после ручного копирования по FTP | Права доступа или владелец файлов | Проверить права согласно требованиям хостинга |
| Ошибка после обновления CMS | Несовместимая версия модуля | Найти актуальную сборку модуля у разработчика |
| Модуль виден, но не устанавливается | Расхождение идентификатора и имени класса | Сверить имя папки и класс в файле описания |
Когда обращаться к разработчику модуля
Если все проверки пройдены, а установщик по-прежнему не видит файл описания, проблема может быть в самой сборке модуля. Соберите диагностическую информацию: версию CMS, текст ошибки, скриншот структуры папок модуля — и направьте в поддержку разработчика модуля или на форум вашей платформы.
Что приложить к обращению в поддержку
Версию и редакцию CMS, точный текст ошибки, скриншот структуры каталогов модуля на сервере, источник дистрибутива (маркетплейс, сайт разработчика), а также описание действий, после которых появилась ошибка. Это заметно ускорит диагностику.
Не пытайтесь самостоятельно переписывать файл описания модуля, если вы не разработчик: ошибка в манифесте влияет на регистрацию модуля в системе, права доступа и обработчики событий.
Частые вопросы
Можно ли просто создать файл описания вручную?
Нет. Файл описания содержит класс с параметрами установки, зависимостями и регистрацией обработчиков. Пустой или самодельный файл приведёт к некорректной установке модуля и возможным сбоям сайта. Нужно восстановить оригинальный файл из дистрибутива.
Почему модуль работал на старом сайте, а после переноса появилась ошибка?
Возможные причины — потеря части файлов при копировании, смена владельца файлов на новом сервере или другая версия CMS. Проверьте целостность папки модуля, права доступа и совместимость версий.
Где искать файл описания модуля в 1С-Битрикс?
Обычно это install/index.php внутри каталога модуля — там объявляется класс с идентификатором модуля. Рядом часто находится install/version.php с номером версии. Точные требования приведены в документации для разработчиков платформы.
Поможет ли переустановка CMS?
Нет, ошибка относится к конкретному модулю, а не к ядру системы. Переустановка платформы — избыточная мера с риском потери данных. Достаточно восстановить корректную структуру самого модуля.
Ошибка появилась при обновлении модуля, а не при установке. Что делать?
Откатите модуль из резервной копии, проверьте, что обновление предназначено для вашей версии CMS, и повторите процедуру. Если ошибка повторяется — обратитесь к разработчику модуля, возможно, пакет обновления собран с дефектом.