Обещание результата: за 10–15 минут вы проверите наличие файлов модуля, корректность пролога, переменные окружения в CLI/CRON, автозагрузку, версии PHP и права — и либо сразу устраните ошибку, либо получите чёткий чек-лист для восстановления.
Быстрые решения: 10 способов устранить ошибку «Не найден модуль main»
1) Подключить пролог: prolog_before.php или header.php
Ядро подключается прологом. Если файл вызывает функции Битрикс напрямую (CModule, Loader и т. п.) — без пролога модуль main действительно «не найден».
<?php
// ./local/tools/my-script.php
// ВАЖНО: корректный путь к прологу относительно DOCUMENT_ROOT
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
// дальше — ваш код
use Bitrix\Main\Loader;
Loader::includeModule('iblock'); // пример подключения стороннего модуля
?>2) Исправить DOCUMENT_ROOT и абсолютные пути
В CLI/CRON переменная $_SERVER['DOCUMENT_ROOT'] пустая. Нужна инициализация.
<?php
// ./local/cron/jobs/export.php
$_SERVER['DOCUMENT_ROOT'] = realpath(__DIR__ . '/../../..');
$_SERVER['HTTP_HOST'] = 'example.ru';
define('NO_KEEP_STATISTIC', true);
define('NOT_CHECK_PERMISSIONS', true);
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
?>3) Проверить наличие /bitrix/modules/main/ и права 755/644
Права и владение — типичная причина после деплоя.
# из корня проекта
ls -la bitrix/modules/main
# актуализируем права
find bitrix/modules/main -type d -exec chmod 755 {} \;
find bitrix/modules/main -type f -exec chmod 644 {} \;4) Очистить кеш: /bitrix/cache, /bitrix/managed_cache, /bitrix/stack_cache
Поврежденный кеш может «прятать» модуль. Очистите и перезапустите PHP‑FPM.
rm -rf bitrix/cache/* bitrix/managed_cache/* bitrix/stack_cache/*
# для BitrixVM 9
bx-fpm restart5) Не вызывать IncludeModule('main') — ядро подключается прологом
Вызовы CModule::IncludeModule('main') и Loader::includeModule('main') не нужны. Если такой вызов присутствует — удаляем.
6) Отключить конфликтующий vendor/autoload.php до пролога
Composer иногда подменяет автозагрузчик. Подключайте его после пролога.
<?php
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
// Только после пролога
require $_SERVER['DOCUMENT_ROOT'] . '/local/vendor/autoload.php';
?>7) Запуск в CLI/CRON: задать $_SERVER vars и подключить пролог
Проверить: путь к прологу, HTTP_HOST, таймзону, отдельный php.ini для cron.
8) Свернуть утерянные файлы из бэкапа/репозитория
Отсутствие include.php или version.php в /bitrix/modules/main — критично. Верните файлы из Git/архива.
9) Обновить ядро через /bitrix/admin/update_system.php
После частичных обновлений иногда помогает повторная установка обновлений ядра.
10) Проверить версию PHP 8.1/8.2 и недостающие расширения
Не хватает ext-json, intl, mbstring — модуль может «падать» при инициализации.
Причины ошибки 'Не найден модуль main'
Отсутствует или повреждён /bitrix/modules/main/
Банально, но встречается после «частичной заливки» на хостинг или неудачного обновления. Без include.php ядро не поднимется.
Скрипт выполняется в обход пролога (ajax, cron, cli)
Самописные ajax‑точки из /local/ без пролога — классика. Проверяем, что любой код, использующий классы Битрикс, идёт после пролога.
Неверные пути/докрут: контейнеры, chroot, symlink
В Docker/Podman пути и DOCUMENT_ROOT отличаются. Симлинки могут указывать на отсутствующие каталоги внутри chroot. Проверьте реальный путь через realpath().
Конфликт автозагрузчиков (Composer vs Bitrix)
Если Composer подключён первым, он может перехватить автозагрузку и сломать find‑логику Bitrix. Порядок загрузки критичен.
Несовместимость PHP/расширений или open_basedir
Жёсткие ограничения open_basedir не дают читать /bitrix/modules. Отсутствующие расширения ломают инициализацию.
Сбой обновления, частичная заливка на хостинг
Встречали кейсы, когда при развертывании пропускалась папка lib/ или js/, из‑за .gitignore. Результат — не найден модуль.
Проверка наличия файлов модуля
Структура: /bitrix/modules/main/, include.php, lib/, classes/, version.php
tree -L 2 bitrix/modules/main
# ожидаем:
# bitrix/modules/main/
# ├── admin/
# ├── classes/
# ├── include.php
# ├── install/
# ├── lib/
# ├── lang/
# ├── options.php
# └── version.phpСравнение версий и целостности с репозиторием/бэкапом
Сверьте version.php с боевой/стендовой копией. При несовпадении — восстановить точную версию папки main.
Права/владение, блокировки, антивирус, квоты диска
Проверьте владельца файлов (www-data/nginx) и свободное место. Антивирусы хостеров иногда карантинят файлы.
df -h
chown -R www-data:www-data bitrix/modules/main
getfacl bitrix/modules/main | head -n 20
# Подозрения на блокировку или карантин — в техподдержку хостингаПравильность подключения модуля
Рекомендуемый путь: подключение пролога до любого кода
<?php
// ./local/ajax/form.php
define('STOP_STATISTICS', true);
define('PUBLIC_AJAX_MODE', true);
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
// ваш код, работа с POST и компонентами
?>Loader::includeModule для сторонних модулей, не для main
<?php
use Bitrix\Main\Loader;
// Не нужно:
// Loader::includeModule('main');
// Нужно — для сторонних модулей:
Loader::includeModule('iblock');
Loader::includeModule('catalog');
?>Типовые подключения в компонентах, ajax‑точках, REST
Компоненты, размещённые в шаблонах, подключают прологи автоматически через header.php. Самописные эндпоинты — нет, это на нашей совести.
Антипаттерны: локальный require ядра, дублирование init
- require 'bitrix/modules/main/include.php' напрямую — плохо;
- двойной пролог — лишние накладные расходы;
- подключение init.php до пролога — нарушает порядок событий.
Восстановление модулей через консоль
Развёртывание из бэкапа (restore.php, архив проекта, CI)
Если модуль исчез — быстро восстановите из последнего бэкапа. В CI/CD держите артефакт с /bitrix/modules/main соответствующей версии.
Точечное восстановление папки main соответствующей версии
# пример восстановления только папки main из артефакта
tar -xzf artifacts/bitrix-main-23.500.0.tar.gz -C bitrix/modules/Запуск обновлений: /bitrix/admin/update_system.php (при web‑доступе)
Если админка доступна, запустите обновления ядра. При проблемах с авторизацией — временно включить отображение ошибок в локальной среде.
Проверка версии в version.php и согласование с ядром
<?php
// ./bitrix/modules/main/version.php
$arModuleVersion = [
'VERSION' => '23.500.0',
'VERSION_DATE' => '2024-02-15 12:00:00',
];Важно: в проектах на BitrixVM 9 проверяйте и системные обновления окружения. Иногда помогает перезапуск служб и очистка opcache перед повторной попыткой.
Работа с autoload и init.php
Порядок: пролог → local/php_interface/init.php → события
<?php
// ./local/php_interface/init.php
use Bitrix\Main\EventManager;
// Этот файл загружается ПОСЛЕ пролога, не раньше
EventManager::getInstance()->addEventHandler('main', 'OnBeforeUserRegister', function (&$fields) {
// ваши хендлеры
});Регистрация классов: Loader::registerAutoLoadClasses
<?php
use Bitrix\Main\Loader;
Loader::registerAutoLoadClasses(null, [
'Rosveb\\Tools\\Exporter' => '/local/lib/Rosveb/Tools/Exporter.php',
]);Composer: подключать после пролога, без замены Bitrix autoload
<?php
// ./local/php_interface/init.php
// Подключаем composer после пролога и до ваших классов
$composer = $_SERVER['DOCUMENT_ROOT'] . '/local/vendor/autoload.php';
if (file_exists($composer)) {
require $composer;
}Диагностика без глубокой отладки
Проверка логов PHP/Bitrix, error_reporting, display_errors=Off
# Веб-сервер
tail -f /var/log/nginx/error.log
# PHP-FPM
tail -f /var/log/php8.1-fpm.logbitrix/.settings.php: включение логирования исключений
<?php
// ./bitrix/.settings.php
return [
'exception_handling' => [
'value' => [
'debug' => true,
'handled_errors_types' => E_ALL & ~E_NOTICE,
'exception_errors_types' => E_ALL & ~E_NOTICE,
'log' => ['class_name' => '\\Bitrix\\Main\\Diag\\FileExceptionHandler', 'settings' => ['file' => '/bitrix/logs/bitrix_exceptions.log']],
],
'readonly' => false,
],
];phpinfo: пути, расширения, open_basedir, opcache
<?php
// ./local/tools/phpinfo.php
phpinfo();После каждого технического шага сделайте короткую проверку: открывается ли главная, работает ли нужный скрипт, нет ли новых ошибок в логах.
CLI/CRON: «битрикс ошибка не найден модуль main»
Установка $_SERVER['DOCUMENT_ROOT'], $_SERVER['HTTP_HOST']
<?php
// ./local/cron/report.php
$_SERVER['DOCUMENT_ROOT'] = realpath(__DIR__ . '/../../..');
$_SERVER['HTTP_HOST'] = 'rosveb.ru';
define('NO_KEEP_STATISTIC', true);
define('NOT_CHECK_PERMISSIONS', true);
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
// ... код отчёта
?>require prolog_before.php, NO_KEEP_STATISTIC, NOT_CHECK_PERMISSIONS
Эти константы снижают накладные расходы и отключают статистику. На долгих задачах — обязательно.
Отдельные php.ini для cron, пути в контейнерах
# crontab -e
* * * * * /usr/bin/php -c /etc/php/8.1/cli/php.ini /var/www/html/local/cron/report.php >/dev/null 2>&1В Docker прописывайте корректные volume и пути. Если /bitrix симлинкован — проверьте, куда он указывает внутри контейнера.
Совместимость PHP и окружения (2024–2026)
PHP 8.1–8.2, ext-json, mbstring, intl, zip, gd
| Компонент | Требование | Комментарий |
|---|---|---|
| PHP | 8.1 или 8.2 | Сверяйтесь с релиз-нотами Битрикс |
| Расширения | json, mbstring, intl, zip, gd, xml, curl | Отсутствие любого может повлиять на загрузку модуля |
| Opcache | Включён | После деплоя — reset, чтобы избежать «залипаний» |
Opcache reset после деплоя, корректный umask
php -r 'opcache_reset();'
umask 022 # чтобы новые файлы не получали странных правСпецифические кейсы
Мультисайт: правильный сайт‑контекст и хост
В CLI указывайте $_SERVER['HTTP_HOST'] конкретного сайта. В противном случае контекст инициализируется неверно и часть настроек ядра не подтянется.
Композитный режим и кеш ядра
Композит иногда маскирует проблемы. При массовых ошибках отключите композит, очистите кеши, убедитесь, что prolog_before.php не переопределён в шаблоне.
Реальная история: падение на «не найден модуль main» случилось из‑за того, что дев‑скрипт в /local/tools/ исполнялся кроном без DOCUMENT_ROOT. Добавили 3 строки и пролог — и проблема исчезла. Простые вещи спасают.
Профилактика
CI/CD с проверкой наличия /bitrix/modules/main/
// Пример шага в CI (псевдокод)
if (!fs.existsSync('bitrix/modules/main/include.php')) {
throw new Error('Missing /bitrix/modules/main/include.php');
}Мониторинг cron‑тасков, интеграционные smoke‑тесты пролога
- Тест «поднимается ли пролог» — скрипт, возвращающий 200 и версию ядра;
- Алерт на ошибки «include failed» в логах;
- Проверка свободного места и прав перед деплоем.
Лайфхаки
- Храните точную копию папки main в артефактах сборки.
- Composer подключайте после пролога — всегда.
- Для CLI используйте bootstrap‑файл с общими установками SERVER и пролога.
- Искать «битрикс ошибка не найден модуль main» удобно с готовым чек-листом — сохраняйте его в репозитории проекта.
- ИИ‑модели помогают сверстать cron‑bootstrap и быстро отрефакторить точки подключения пролога.
Диагностика без глубокой отладки
Короткий чек‑лист
- Есть ли /bitrix/modules/main/include.php?
- Подключается ли пролог до любого кода?
- Задан ли DOCUMENT_ROOT в CLI/CRON?
- Нет ли раннего vendor/autoload.php до пролога?
- Права/владение корректны?
- Расширения PHP в наличии?
- Кеш и opcache очищены?
Мини‑пример шаблона для проверки пролога
<!-- ./local/templates/.default/header.php -->
<?php
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
?>
<header>
<div class="logo">rosveb.ru</div>
</header>Риски и их минимизация
- Риск: потеря файлов ядра при деплое. Митигирование: атомарные релизы, артефакты и «сухие» прогонки.
- Риск: конфликт автозагрузок. Митигирование: Composer после пролога, тест в CI.
- Риск: разные php.ini для веба и CLI. Митигирование: явное указание php.ini в crontab, phpinfo‑снимки.
- Риск: open_basedir ограничивает /bitrix. Митигирование: добавьте нужные пути или отключите ограничение в контейнере.
FAQ
Можно ли «подключить модуль main» через Loader::includeModule('main')?
Нет. Модуль main подключается прологом. Вызовы includeModule для него — избыточны и вредны.
Почему в cron всё падало, а в браузере — нет?
В браузере автоматом задан DOCUMENT_ROOT и подключён пролог через шаблон. В cron это делаете вы.
Где смотреть лог исключений Битрикс?
Если включено в bitrix/.settings.php, файл по умолчанию: /bitrix/logs/bitrix_exceptions.log.
Нужно ли обновляться до BitrixVM 9 ради этой проблемы?
Не обязательно. Но BitrixVM 9 упрощает управление службами и opcache, что полезно при восстановлении.
Как проверить, что конкретно ломает автозагрузку?
Временно закомментируйте подключение vendor/autoload.php. Если ошибка исчезла — конфликт в Composer. Переставьте порядок.
Выводы и рекомендации
Ошибка «Не найден модуль main» почти всегда решается быстро: пролог, корректные пути, целостность папки /bitrix/modules/main, порядок автозагрузок и актуальное окружение. Важно действовать методично и проверять результат после каждого шага — тогда и прод, и cron, и любые вспомогательные скрипты оживают без длительной отладки.
- Сохраните чек‑лист проверки пролога и DOCUMENT_ROOT в репозитории.
- Настройте CI для контроля целостности папки main и проверки наличия расширений PHP.
- Подумайте о едином bootstrap для CLI: пролог + переменные окружения.
- Если проблема не уходит — обратитесь к специалисту: быстрая ревизия окружения и кода часто экономит дни.
Готовы помочь: разберём логи, проверим окружение, поправим автозагрузку и деплой. А пока — загляните в свои скрипты и убедитесь, что пролог действительно там, где должен быть.
