Configuration and troubleshooting

config.yml keeps administrator edits. Missing keys use current defaults without rewriting the file, while config.reference.yml is regenerated on startup as the complete reference. Migrate refuses configuration created by a newer plugin version.

Important settings #

migration.confirmation-timeout-seconds: time allowed between start and confirm.
migration.dry-run-validity-minutes: how long a dry-run result remains valid.
migration.max-records: maximum records accepted in a plan.
performance.batch-size: records written in one batch.
performance.pause-between-batches-ms: pause between batches; increase it on a busy server.
conflicts.defaults: default resolution for each conflict type.
world-mappings and currency-mappings: explicit source-to-target mappings.
identity.create-missing-players: permits creation of missing HuskHomes user rows; disabled by default.
connections.advancedban and connections.litebans: explicitly configured MariaDB/MySQL connections.
compatibility.allow-unverified-versions: allows newer, unverified plugin versions to reach the stricter dry run; disable it to block them.

Migrate's own state database is SQLite. Alternative state-database options are not verified for 1.0.0 and require the matching JDBC driver to be installed on the server.

Conflict policies #

The dry run shows every conflict and the policy that will be applied. Safe defaults keep existing target records and skip invalid or unsupported data. Other route-appropriate policies include OVERWRITE, RENAME, KEEP_NEWEST, KEEP_OLDEST, MANUAL and FAIL_MIGRATION.

text

/migrate conflicts MIG-20261008-0001
/migrate resolve MIG-20261008-0001 INVALID_WORLD SKIP
/migrate dryrun MIG-20261008-0001

Run the dry run again after changing a policy or mapping.

Backups and reports #

Before the first write, Migrate records normalized data, target before-images, permitted source/target file copies, the active configuration and SHA-256 checksums under plugins/Migrate/backups/<id>/. Backups are never deleted automatically.

Each migration writes JSON, text and HTML reports under plugins/Migrate/reports/; skipped records also receive a CSV report. /migrate backups <id> verifies the stored checksums.

Languages #

Migrate includes English, Turkish, German, Spanish, French, Brazilian Portuguese, Polish, Russian, Simplified Chinese and Japanese. Select one with /migrate language <locale> or language.default. Missing message keys fall back to English.

Troubleshooting #

Message or condition	Action
Dry run is too old	Run `/migrate dryrun <id>` again.
Target plugin must be disabled	Remove or disable the target jar, restart the server and start again.
Version is unverified	Inspect the dry-run warnings; disable `compatibility.allow-unverified-versions` if such versions must be blocked.
`connections.<plugin>` is not set	Complete that connection section and run `/migrate reload`.
Another migration is writing to the target	Wait for it or inspect `/migrate history`.
Configuration was not reloaded	Correct the exact invalid path named in the message; the previous settings remain active.
Migration was interrupted	Run `/migrate inspect <id>`, then choose `resume` or `rollback`.

For support, include /migrate diagnostics, /migrate compatibility, /migrate adapters, the migration's text report and relevant server log lines. Remove passwords and server addresses from anything you share.