Диагностика

status --strict вернул 2

Это означает, что хотя бы одна группа pending, drifted, missing или outOfOrder не пуста. Запустите обычный status, затем разберите соответствующий раздел ниже. Сам код 2 не означает ошибку PHP или подключения MODX.

pending больше нуля

Файл ещё не применён либо его последняя попытка имеет статус failed.

1. Посмотрите очередь через up --dry-run.
2. Если это failed-файл, прочитайте output его строки в таблице журнала.
3. Исправьте причину так, чтобы миграция безопасно пережила уже выполненную часть.
4. Повторите up.

Не меняйте успешно применённые старые файлы вместе с исправлением — это создаст drift. Для дополнительного изменения создайте новую миграцию.

drifted больше нуля

SHA-256 файла отличается от значения, записанного при применении.

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

up --ignore-checksum допустим только когда:

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

Dry-run с флагом показывает строки [ACCEPTED], но журнал меняет только обычный up --ignore-checksum.

missing больше нуля

Журнал знает миграцию, которой нет в каталоге. Обычно файл удалили, переименовали или не доставили на эту среду.

Верните тот же файл с тем же именем и содержимым. Раннер намеренно не удаляет историю автоматически и не предоставляет команду «забыть миграцию».

outOfOrder больше нуля

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

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

--allow-out-of-order используйте только при осознанном восстановлении истории: он отключает защиту, но не анализирует зависимости между миграциями.

Миграции уже выполняет другой процесс

MySQL не выдал проектную блокировку без ожидания. Проверьте deploy, cron и ручные SSH-сессии, работающие с той же базой.

Не пытайтесь обходить блокировку вторым конфигом: два процесса смогут одновременно менять схему. Если процесс аварийно завершён, MySQL освобождает advisory lock при закрытии его соединения.

Каталог миграций не найден

Проверьте migrations_path и правило разрешения путей: относительное значение считается от каталога PHP-конфига. Для status и up каталог должен существовать.

Команда new --apply создаёт отсутствующий каталог с режимом 0775, но родительский каталог должен быть доступен на запись текущему пользователю.

Не найден bootstrap MODX

Неверен modx_root. Он должен указывать на корень конкретной установки MODX, а не на core/ или каталог компонента.

• линия MODX 2 ищет <modx_root>/index.php;
• линия MODX 3 ищет <modx_root>/config.core.php, а затем Composer autoload в корне сайта или core/.

Для конфига core/config/mxmigrations.php типовое значение:

'modx_root' => dirname(__DIR__, 2),

Project autoload или класс провайдера не найден

Проверьте по порядку:

1. каждый путь из autoload существует относительно каталога конфига;
2. Composer autoload содержит namespace проекта;
3. класс из recipe_providers загружается этим autoload;
4. класс имеет публичный конструктор без обязательных аргументов;
5. объект реализует MigrationRecipeProviderInterface.

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

model:build требует сначала применить миграцию

В реестре изменений модели есть миграция, которая ещё не отмечена применённой. Выполните up --dry-run, затем up. Модель разрешено записывать только после успешного изменения базы, иначе xPDO начнёт использовать поля, которых ещё нет.

Таблица найдена в нескольких моделях

Одна таблица описана в нескольких XML-схемах из раздела models. Повторите new с явным --model=имя. Пакет не выбирает владельца произвольно, потому что это изменило бы не ту схему и каталог модели.

После обновления miniShop исчезли проектные поля модели

Убедитесь, что для сторонней модели включён overlay => true, а файл migrations/.mxmigrations/model-changes.php доставлен из репозитория. Затем повторите model:build --model=minishop2 --apply: проектные изменения будут наложены на обновлённую штатную схему.

PHP-миграция ничего не вернула

Новый файл обязан завершаться callable. Для MODX 2:

return function (modX $modx): void {
    // Изменение.
};

Для MODX 3 тип аргумента — \MODX\Revolution\modX.

Если файл сам выполняет bootstrap ядра, он относится к legacy-формату и должен завершаться как самостоятельный CLI-скрипт с кодом 0. Не смешивайте два формата в одном файле.

baseline отметил лишние файлы

baseline помечает все текущие pending одним вызовом и не имеет фильтра по имени. До команды обязательно проверяйте status и содержимое каталога.

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

Безопасная последовательность в CI

php core/components/mxmigrations/bin/mxmigrations.php status --strict
php core/components/mxmigrations/bin/mxmigrations.php up --dry-run
php core/components/mxmigrations/bin/mxmigrations.php up --by=deploy
php core/components/mxmigrations/bin/mxmigrations.php status --strict

Во всех командах выше подразумевается --config=... или MXMIGRATIONS_CONFIG. Перед up добавьте резервную копию средствами проекта: mxMigrations отвечает за историю изменений, но не создаёт бэкап.