MODX не работает: как найти причину ошибки и восстановить сайт

Когда MODX не работает, важно сначала определить границы сбоя. Ошибка одной формы и полностью недоступный сайт требуют разной диагностики, хотя внешне пользователь может воспринимать обе ситуации одинаково — «сайт сломался».

Поэтому восстановление лучше начинать не со случайного изменения файлов и настроек, а с ответа на три вопроса:

1. что именно перестало работать;
2. после какого события появилась проблема;
3. какая ошибка зафиксирована в MODX, PHP или веб-сервере.

Так гораздо быстрее отделить проблему ядра MODX от ошибки сниппета, Extra, PHP, базы данных, кэша или серверной конфигурации.

Сначала определите, что именно не работает

Фраза «не работает MODX» может описывать совершенно разные симптомы.

Например:

• весь сайт возвращает HTTP 500;
• главная страница открывается, а внутренние — нет;
• вместо страницы отображается пустой экран;
• MODX Manager не загружается;
• Manager открывается, но отдельный раздел выдаёт ошибку;
• сайт работает, но не отправляются формы;
• перестал работать каталог или miniShop2;
• проблема касается только одного шаблона;
• ошибка появляется после сохранения ресурса;
• сайт сломался после обновления PHP;
• проблема появилась после установки или обновления Extra;
• сайт перестал работать после переноса на другой сервер.

Это первая полезная развилка диагностики.

Если не работает вообще ничего, проверяются системные зависимости: PHP, база, конфигурация, права, сервер и критические ошибки PHP.

Если ломается только определённая функция, область поиска уже значительно меньше.

Например, если обычные страницы MODX работают, но форма FormIt возвращает ошибку, переустанавливать ядро CMS нет смысла — сначала нужно разбирать вызов формы, hooks и связанный код.

Зафиксируйте момент появления ошибки

Очень полезно установить, что происходило непосредственно перед сбоем.

Типичные события:

• обновили PHP;
• обновили MODX;
• установили новый Extra;
• обновили существующий компонент;
• изменили сниппет;
• отредактировали plugin;
• перенесли сайт;
• сменили хостинг;
• изменили nginx или .htaccess;
• поменяли доступ к базе;
• закончилось место на диске;
• изменились права файлов.

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

При этом совпадение по времени ещё не доказывает причину. Задача диагностики — подтвердить её логами и воспроизводимым поведением.

Ошибка 500 в MODX: сначала смотрите логи

HTTP 500 означает, что запрос завершился внутренней ошибкой сервера, но сам статус не объясняет её причину.

За одной и той же ошибкой 500 могут скрываться:

• PHP fatal error;
• несовместимый код;
• проблема при загрузке класса;
• ошибка плагина;
• сбой сниппета;
• неверная серверная конфигурация;
• проблема прав;
• повреждённый кэш;
• ошибка Extra.

Поэтому полезнее получить реальное сообщение об ошибке, чем пытаться устранить сам код 500.

MODX ведёт собственный журнал ошибок. В актуальной структуре MODX основной файловый лог находится в:

core/cache/logs/error.log

Также ошибка может быть видна в разделе Error Log в Manager. Если выполнение PHP обрывается раньше, чем MODX успевает записать событие, нужно смотреть PHP-FPM, Apache или nginx error log. Официальная документация MODX сама рекомендует при диагностике собирать MODX error log, browser console и server error logs.

Важно смотреть не только последнюю строку.

Обычно полезны:

• время ошибки;
• тип PHP error;
• файл;
• номер строки;
• stack trace;
• название вызываемого компонента или класса;
• несколько строк непосредственно перед основной ошибкой.

Так можно понять, сломалось ли ядро, собственный код или установленное расширение.

Кэш MODX может быть частью проблемы

MODX активно использует кэш для конфигурации, ресурсов, Elements, контекстов и других данных. Документация актуальной ветки указывает, что содержимое core/cache/ является генерируемым и MODX способен пересоздать его по запросу.

Повреждённый или устаревший кэш иногда проявляется как:

• пустая страница;
• HTTP 500;
• странное поведение Manager;
• использование старой версии элемента;
• ошибка после переноса;
• проблема сразу после изменения конфигурации.

В официальном troubleshooting MODX отдельно описан случай, когда 500 в Manager может быть связан с повреждённым core/cache.

Но очистку кэша не стоит воспринимать как универсальное лечение.

Если сниппет содержит fatal error, PHP несовместим с кодом или подключение к базе настроено неправильно, пересоздание кэша настоящую причину не устранит.

Правильная последовательность такая:

зафиксировать ошибку → определить источник → при необходимости очистить кэш → проверить результат повторно.

Проверьте версию PHP

Одна из частых причин, почему старый сайт MODX внезапно перестаёт работать, — смена PHP на сервере.

Например, хостинг обновил PHP автоматически, сайт перенесли на другой сервер или администратор переключил версию вручную.

У актуального MODX 3 требования довольно конкретные: текущая документация указывает минимум PHP 8.1, причём этот минимум действует начиная с MODX 3.2; для текущих релизов рекомендуется PHP 8.2 или новее. Но старые проекты нужно оценивать по фактической версии MODX и установленным Extras, а не просто переключать на максимально новую PHP.

Особенно это важно для MODX 2.x.

Старый сайт может содержать:

• устаревший синтаксис PHP;
• старый custom snippet;
• неподдерживаемый Extra;
• собственный компонент;
• старые библиотеки.

В результате сам веб-сервер работает, база доступна, а PHP прекращает выполнение на несовместимом участке кода.

Поэтому при внезапном сбое после смены окружения полезно сравнить:

какая версия PHP была → какая стала → какая версия MODX установлена → какой код падает по логу.

Проверьте обязательные PHP-расширения

Проблемой может быть не только номер версии PHP.

Для актуального MODX требуются несколько PHP-расширений, включая curl, dom, fileinfo, gd, json, pdo, simplexml, xml, xmlwriter, zip, zlib; при работе с MySQL также используется pdo_mysql.

После переноса на новый VPS или смены PHP бывает ситуация, когда версия правильная, но часть модулей не установлена для нового PHP.

Например, CLI может использовать одну версию PHP, сайт через PHP-FPM — другую, а нужный extension установлен только для первой.

Поэтому при серверной диагностике важно проверять именно то PHP-окружение, которое обслуживает сайт.

Если MODX перестал работать после обновления

Обновление MODX и обновление обычного небольшого плагина — не одно и то же.

Особенно внимательно нужно относиться к переходу с MODX 2.x на MODX 3.x.

Официальная документация MODX перечисляет реальные breaking changes: изменены и перемещены многие классы, processors и model classes, xPDO 3 использует другую структуру и PSR-4, а core в MODX 3 больше нельзя размещать произвольно так, как это допускалось в некоторых старых конфигурациях.

Поэтому после серьёзного обновления могут перестать работать:

• custom snippets;
• plugins;
• собственные processors;
• старые Extras;
• custom database packages;
• прямые include или require;
• код, который наследуется от переименованных классов.

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

Для рабочих сайтов обновление лучше проводить с резервной копией и возможностью быстро вернуть предыдущую рабочую версию.

Extra или plugin может остановить весь сайт

Плагин MODX может срабатывать на системных событиях автоматически.

Поэтому ошибка в plugin иногда влияет не на одну страницу, а сразу на большой участок сайта или Manager.

Похожая ситуация возможна с Extra, который:

• несовместим с PHP;
• использует старый API;
• не полностью обновился;
• ожидает отсутствующий класс;
• имеет собственные таблицы или модель;
• зависит от другого компонента.

Если лог указывает на конкретный component или plugin, лучше сначала локализовать именно его влияние.

Отключать подряд все компоненты на production без понимания зависимостей рискованно: некоторые из них могут обеспечивать авторизацию, каталог, формы или другие бизнес-функции.

Если не работает только сниппет

Когда остальные страницы сайта открываются, а ошибка возникает только там, где вызывается конкретный snippet, это уже хороший диагностический признак.

Нужно проверить:

• сам snippet;
• его параметры;
• используемые Chunks;
• вызовы других snippets;
• работу с базой;
• подключаемые PHP-файлы;
• API внешних сервисов;
• совместимость кода с текущей PHP.

Особенно полезно сравнить одну работающую страницу и одну неработающую.

Если общий шаблон одинаков, но проблема появляется только при определённом вызове, область поиска резко сокращается.

При вызове FormIt появляется ошибка 500

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

Здесь важно определить момент сбоя:

• ошибка возникает до валидации;
• ошибка появляется внутри FormIt;
• падает один из hooks;
• проблема возникает при отправке email;
• custom hook обращается к внешней CRM/API;
• после успешной обработки ломается redirect.

FormIt запускает hooks в указанном порядке. Для custom hook документация описывает возвращаемый результат: при неуспешном выполнении он может остановить последующие hooks. Для стандартного redirect отдельно указано, что его следует размещать последним.

Поэтому ситуация:

FormIt → custom hook → CRM → email → redirect

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

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

Если 500 появляется только после отправки формы, а обычная загрузка страницы работает, это значительно полезнее для поиска причины, чем общее утверждение «MODX сломан».

Проверьте подключение к базе данных

Без рабочей базы MODX не сможет нормально загружать ресурсы, настройки, пользователей и многие другие данные.

Проблемы с базой часто появляются после:

• переноса сайта;
• смены пароля пользователя MySQL;
• изменения hostname;
• восстановления backup;
• изменения прав пользователя;
• недоступности MySQL/MariaDB.

Симптомы могут отличаться в зависимости от стадии загрузки приложения и версии проекта.

При подозрении на базу нужно проверить:

• доступен ли сервер БД;
• существуют ли нужная база и пользователь;
• совпадают ли реквизиты подключения;
• есть ли у пользователя необходимые права;
• завершился ли предыдущий импорт или восстановление без ошибки.

Не нужно переустанавливать MODX только потому, что сайт перестал подключаться к уже существующей базе.

Проверьте свободное место на диске

Иногда проблема выглядит как ошибка CMS, хотя причина находится ниже уровнем.

Если на сервере закончилось свободное место, MODX или PHP могут перестать нормально:

• создавать кэш;
• записывать лог;
• хранить session;
• загружать файлы;
• создавать временные файлы.

Тогда даже журнал MODX может перестать обновляться, что усложняет диагностику.

Поэтому при внезапной серверной проблеме стоит проверить не только код сайта, но и состояние файловой системы.

Права на файлы и каталоги

После переноса, восстановления из архива или изменения пользователя PHP могут появиться неправильные owner/group или permissions.

В результате файлы читаются, но запись в нужный каталог не выполняется.

Это может затронуть:

• core/cache;
• загружаемые изображения;
• временные файлы;
• компоненты;
• создание или обновление кэша.

Решение не должно заключаться в назначении максимально широких прав всему проекту.

Нужно определить пользователя, от которого работает PHP/web-сервер, и дать необходимые права именно там, где они требуются.

Если не открывается MODX Manager

Бывает, что публичная часть сайта работает, а административная панель — нет.

В таком случае нужно отдельно проверить:

• HTTP-код Manager;
• browser console;
• MODX error log;
• server/PHP logs;
• кэш mgr;
• cookies/session;
• доступность JS/CSS;
• PHP errors;
• плагины, срабатывающие в manager context;
• конфигурацию путей после переноса.

Это важно, потому что работа frontend не доказывает исправность Manager.

Например, PHP-код, который выполняется только при mgr-событии, может ломать административную панель и вообще не затрагивать публичные страницы.

Если открывается главная, а внутренние страницы дают 404

Такой симптом часто относится не к «поломке всего MODX», а к Friendly URLs и rewrite-конфигурации.

Актуальная документация MODX отдельно отмечает, что для Friendly URLs требуется соответствующая настройка веб-сервера; конкретные правила отличаются для Apache, nginx и других серверов.

Поэтому при сценарии:

главная — 200, внутренние страницы — 404

стоит проверить:

• .htaccess на Apache;
• nginx rules;
• настройки Friendly URLs;
• virtual host;
• base URL;
• редиректы.

Переустановка CMS в такой ситуации обычно не относится к первопричине.

Если сайт работает частично

Частичная работоспособность — полезный симптом.

Например:

• обычные страницы работают;
• каталог работает;
• корзина работает;
• оформление заказа падает.

Или:

• весь сайт работает;
• одна форма возвращает 500.

Или:

• frontend работает;
• Manager — нет.

Каждый такой сценарий показывает границу между исправной и неисправной частью системы.

Поэтому диагностика должна двигаться от работающего участка к первому месту, где возникает ошибка.

Это быстрее и безопаснее, чем одновременно менять PHP, кэш, базу, плагины и конфигурацию сервера.

Что проверить после восстановления MODX

Сайт нельзя считать восстановленным только потому, что главная страница снова открылась.

После исправления нужно повторно пройти важные сценарии проекта.

Как минимум:

• главную страницу;
• несколько внутренних страниц;
• MODX Manager;
• сохранение ресурса;
• формы;
• поиск, если используется;
• каталог;
• мобильную версию.

Для магазина дополнительно:

• карточка товара;
• корзина;
• оформление заказа;
• доставка;
• платёжный сценарий;
• уведомления.

Для интегрированного проекта:

• CRM;
• API;
• webhook;
• cron;
• обмен данными.

Набор проверок должен соответствовать реальным функциям конкретного сайта.

Сначала восстановить работу — потом обновлять всё остальное

Когда сайт уже лежит, появляется соблазн одновременно:

• обновить MODX;
• сменить PHP;
• обновить Extras;
• переписать проблемный код;
• поменять серверные настройки.

Это резко увеличивает количество переменных.

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

Для аварийной ситуации лучше разделять две задачи:

1. локализовать причину и вернуть рабочее состояние;
2. отдельно планировать обновления и технический долг.

Особенно это относится к старому MODX 2.x и проектам с большим количеством custom-кода.

Что не стоит делать, если MODX перестал работать

Несколько действий могут усложнить восстановление:

• удалять файлы без резервной копии;
• переустанавливать MODX поверх неизвестного состояния;
• массово обновлять Extras во время аварии;
• бесконтрольно менять версию PHP;
• назначать права 777 всему проекту;
• очищать все данные без понимания их назначения;
• скрывать ошибку вместо устранения причины;
• исправлять production без возможности отката.

Ещё одна типичная ошибка — ориентироваться только на внешний симптом.

HTTP 500 — это не диагноз. Белый экран — не диагноз. «Не работает Manager» — тоже не диагноз.

Диагноз появляется, когда найден конкретный сбой и подтверждено, что его исправление восстанавливает нужный сценарий.

Как обычно восстанавливают сайт на MODX

Практический порядок можно свести к нескольким этапам.

1. Фиксируют симптомы

Какие URL не работают, какой HTTP-код возвращается, работает ли Manager, когда появилась проблема.

2. Проверяют логи

MODX, PHP-FPM, nginx/Apache и при необходимости browser console.

3. Локализуют компонент

Ядро, plugin, snippet, Extra, FormIt, база, кэш, PHP или серверная конфигурация.

4. Определяют последнее изменение

Обновление, перенос, изменение PHP, новая версия компонента или custom-кода.

5. Создают безопасную точку восстановления

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

6. Исправляют конкретную причину

Не весь сайт сразу, а найденную неисправность.

7. Повторно проверяют связанные функции

Не только страницу с исходной ошибкой, но и зависимые сценарии.

Такой подход особенно полезен на старом проекте, где техническая структура сайта заранее неизвестна.

Что подготовить для диагностики MODX

Чтобы быстрее определить причину, полезно иметь:

• адрес сайта;
• описание симптома;
• время начала ошибки;
• информацию о последних изменениях;
• версию MODX;
• версию PHP;
• текст ошибки или скриншот;
• несколько строк релевантного лога.

Для самого восстановления в зависимости от проблемы могут потребоваться:

• MODX Manager;
• файлы сайта;
• база данных;
• панель хостинга;
• SSH/VPS.

Набор доступов определяется после первичной диагностики. Передавать доступ ко всем сервисам заранее не требуется.

Можно ли восстановить старый сайт на MODX

Во многих случаях — да.

Сам возраст проекта ещё не означает, что его обязательно нужно полностью переделывать.

Если причина сбоя локализована в:

• несовместимом сниппете;
• plugin;
• PHP;
• кэше;
• FormIt hook;
• настройке сервера;
• подключении к базе;
• конкретном Extra;

можно восстановить существующий проект и уже после этого решать, требуется ли его обновление.

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

FAQ

Что делать, если MODX не работает и показывает ошибку 500?

Сначала нужно получить реальную ошибку из MODX, PHP или server log. Сам HTTP 500 не показывает причину. После этого можно определить, связан ли сбой с PHP, кэшем, plugin, snippet, Extra, правами или серверной конфигурацией.

Где находится лог ошибок MODX?

В стандартной структуре MODX файловый журнал находится в core/cache/logs/error.log. Ошибки также можно просматривать через Error Log в Manager, если административная панель доступна.

Может ли MODX перестать работать после обновления PHP?

Да. Особенно на старых проектах собственный код или Extras могут быть несовместимы с новой версией PHP. При этом для текущих релизов MODX 3.2+ сама CMS требует PHP 8.1 или новее.

Почему при отправке FormIt появляется ошибка 500?

Ошибка может возникать в самом вызове формы, custom hook, отправке письма, интеграции или другом действии после валидации. FormIt выполняет hooks последовательно, поэтому нужно определить конкретный этап, на котором происходит сбой.

Поможет ли очистка кэша MODX?

Иногда да, если проблема связана с повреждёнными или устаревшими данными кэша. MODX пересоздаёт содержимое core/cache по мере необходимости. Но очистка кэша не исправляет несовместимый PHP-код, неправильное подключение к базе или другую реальную причину ошибки.

Нужно ли сразу обновлять MODX, если сайт перестал работать?

Нет. Сначала лучше локализовать причину текущего сбоя и восстановить стабильную работу. Обновление особенно старого MODX 2.x до 3.x может затрагивать несовместимые классы, processors, xPDO и custom-код, поэтому это отдельная техническая задача.

Нужно восстановить сайт на MODX?

Поможем найти причину сбоя MODX, проверить PHP, кэш, FormIt, базу, плагины и серверное окружение, а затем восстановить рабочий сценарий.

↑ К оглавлению