EssentialsC / Migration

Migration

Import player data, homes, warps, economy balances, nicknames, mutes, and bans from an existing EssentialsX install.

Overview

EssentialsC ships with a built-in migration tool for moving off EssentialsX without losing player data. It reads directly from your existing Essentials folder and the server's banned-players.json, then writes the results into EssentialsC's own managers.

Migration runs through /migration <subcommand>. Make sure your old EssentialsX jar has been removed from /plugins before starting the server with EssentialsC, otherwise both plugins will try to manage the same data.
Subcommand Purpose
/migration status Checks whether an EssentialsX folder and ban file exist, and confirms EssentialsC's managers are ready to receive data.
/migration essentialsx Runs the actual import, with optional flags to skip categories, change conflict handling, or perform a dry run.
/migration progress Reports the current stage, percentage complete, and estimated time remaining for an in-progress migration.

Checking Status

Before running a migration, use /migration status to confirm everything is in place. It reports:

  • Whether an Essentials folder was found next to your plugins directory
  • How many user files exist under userdata and how many warps exist under warps
  • Whether banned-players.json is present at the server root
  • Whether EssentialsC's economy, home, nickname, warp, and punishment managers are initialised and ready
If a manager reports as missing, the migration will still attempt to run, but that category of data will fail to import. Check your console for startup errors before proceeding.

Running a Migration

Running /migration essentialsx with no flags imports everything: users, warps, economy balances, homes, nicknames, mutes, and bans, skipping any record that already exists on the EssentialsC side.

command 
/migration essentialsx

Once started, EssentialsC reports the categories being imported, then runs the import asynchronously off the main thread. A live progress message is broadcast to whoever ran the command until the migration finishes. When it completes, you'll get a full breakdown of how many records were migrated, skipped, or failed for each category, followed by up to five warnings if any came up along the way.

Always run with --dry-run first on a production server. It walks through the same logic and reports what it would have done without writing anything.

Flags

Flags are appended after essentialsx and can be combined freely.

Flag Effect
--dry-run Runs the full migration logic without writing any data, so you can preview the outcome safely.
--no-economy Skips importing economy balances.
--no-homes Skips importing player homes.
--no-warps Skips importing warps.
--no-nicks Skips importing nicknames.
--no-mutes Skips importing mutes.
--no-bans Skips importing bans.
--only-warps Imports warps only; turns off users and bans for this run.
--only-bans Imports bans only; turns off users and warps for this run.
--only-mutes Imports user data for mutes only; turns off warps, economy, homes, nicknames, and bans for this run.
The --only-* flags and the --no-* flags both modify the same set of toggles. If you combine them, whichever flag is parsed last wins for that category.

Conflict Strategies

When an incoming record already exists in EssentialsC (a home with the same name, a warp with the same key, and so on), the conflict strategy decides what happens. The default is skip.

Flag Strategy Behavior
default SKIP Leaves the existing EssentialsC record untouched and counts the import as skipped.
--overwrite OVERWRITE Replaces the existing record with the one coming from EssentialsX.
--rename-conflicts RENAME Keeps both records by renaming the incoming one to avoid a clash.
--abort-on-conflict ABORT Stops the migration entirely the moment a conflict is found.

Progress & Results

While a migration is running, /migration progress reports the current stage, how many users and warps have been processed out of the total, the percentage complete, elapsed time, and an estimated time remaining.

When the migration finishes, EssentialsC reports a full results breakdown:

  • Users migrated and users failed
  • Warps migrated and warps failed
  • Homes migrated and homes skipped
  • Economy records imported
  • Nicknames migrated
  • Mutes migrated
  • Bans migrated and bans failed
  • Total warnings raised during the run

If any warnings were raised, the first five are printed directly in chat, with a note for how many more were suppressed if the count goes higher than that.

Permissions

Node Description Default
essentialsc.migration Allows running any /migration subcommand, including starting an EssentialsX import. Operators