Migrate from EssentialsX

What Gets Migrated

EssentialsC includes a built-in migration engine that reads EssentialsX flat-file data and writes it into EssentialsC's SQLite databases. The following data types are supported:

• User profiles — All player records from plugins/Essentials/userdata/<uuid>.yml
• Economy balances — money field from each user's YAML file, transferred to EssentialsC's economy SQLite database. Requires Vault and the EssentialsC economy module to be enabled.
• Homes — All homes from homes: section per user, including world UUID/name, coordinates, yaw, and pitch. Supports online and offline players via OfflineHome fallback storage.
• Nicknames — nickname field, automatically converted from legacy color codes (§) to MiniMessage format using LegacyColorConverter.
• Warps — All .yml files from plugins/Essentials/warps/, including location, last owner UUID, world data, and warp name.
• Mutes — Active mute status (muted, mute-reason, timestamps.mute). Expired mutes are automatically skipped.
• Bans — Server-wide bans from banned-players.json in the server root. Supports permanent and timed bans with expiration parsing.
• Back locations — lastlocation or logoutlocation is set as the player's back location for online players only (requires the player to be online during migration).

Prerequisites

Before running the migration, ensure the following:

• EssentialsX is installed — The migration reads from plugins/Essentials/. Do not delete or move this folder until migration is complete.
• EssentialsC modules are enabled — The target modules (economy, homes, warps, nicknames, punishments) must be enabled in config.yml. The migration validator checks this and skips unavailable modules with a warning.
• Worlds are loaded — The validator scans user data for world UUIDs and names. If a world is missing, homes and warps in that world are skipped. Ensure all worlds from your old server are present.
• Back up EssentialsC data — While the migrator uses conflict resolution strategies, it's safest to back up plugins/EssentialsC/database/ before starting.

Running the Migration

The migration is executed via the /migration command. It runs asynchronously and reports progress in real time.

Basic migration (everything)

/migration essentialsx

This imports users, warps, economy, homes, nicknames, mutes, and bans using the default SKIP conflict strategy.

Dry run (preview without writing)

/migration essentialsx --dry-run

Validates all data, counts records, and simulates the migration without writing to EssentialsC's databases. Use this to estimate duration and catch errors.

Conflict strategies

When a warp name or home name already exists in EssentialsC, the migrator uses a conflict strategy:

• --overwrite — Replace existing EssentialsC data with EssentialsX data
• --rename-conflicts — Rename conflicting warps to <name>_migrated and homes to <name>_backup
• --abort-on-conflict — Stop the entire migration immediately on any conflict
• --skip (default) — Skip the conflicting record and continue

/migration essentialsx --overwrite
/migration essentialsx --rename-conflicts
/migration essentialsx --abort-on-conflict

Selective migration

Import only specific data types:

• --no-economy — Skip balance migration
• --no-homes — Skip home migration
• --no-warps — Skip warp migration
• --no-nicks — Skip nickname migration
• --no-mutes — Skip mute migration
• --no-bans — Skip ban migration

/migration essentialsx --no-economy --no-nicks
/migration essentialsx --only-warps
/migration essentialsx --only-bans
/migration essentialsx --only-mutes

Combined example

/migration essentialsx --dry-run --rename-conflicts --no-bans

Migration Stages

The migrator runs in four stages, each updating the progress tracker:

1. Validating — Scans plugins/Essentials/, counts userdata and warp files, checks world availability, and verifies EssentialsC manager availability. If validation fails, the migration aborts before any data is touched.
2. Migrating Warps — Reads each .yml from warps/, transforms coordinates into Bukkit Location objects, resolves conflicts, and writes to the warp database.
3. Migrating Users — Iterates all userdata/<uuid>.yml files. For each user, economy, homes, nicknames, mutes, and back locations are processed independently. One user's failure does not stop the migration.
4. Migrating Bans — Parses banned-players.json from the server root, checks if the player is still banned, and writes active bans to EssentialsC's punishment database.

Monitoring Progress

During an active migration, check status with:

/migration progress

This outputs the current stage, processed/total users, processed/total warps, percent complete, elapsed time, and estimated time remaining.

Before starting, inspect what EssentialsC found:

/migration status

This reports:

• Whether the EssentialsX folder was found
• Number of user data files and warp files detected
• Whether banned-players.json exists
• Status of each EssentialsC manager (Economy, Homes, Nicks, Warps, Punishments)

Understanding the Results

When migration completes, a summary is printed:

Migration complete!
Users migrated: 1,247 (failed: 3)
Warps migrated: 42 (failed: 0)
Homes migrated: 3,891 (skipped: 47)
Economy records: 1,247
Nicknames migrated: 312
Mutes migrated: 18
Bans migrated: 56 (failed: 2)
Warnings: 5

• Migrated — Successfully written to EssentialsC
• Failed — Could not be read, transformed, or written (check console for stack traces)
• Skipped — Conflict resolution chose to skip, or the record was invalid (e.g., expired mute, missing world)
• Warnings — Non-fatal issues such as "Economy manager not available" or "Invalid UUID in filename"

If warnings exceed 5, only the first 5 are shown in chat, with a count of additional warnings.

Data Mapping Details

Here is how EssentialsX fields map to EssentialsC:

Troubleshooting

"EssentialsX folder not found"

The migrator looks for plugins/Essentials/ relative to EssentialsC's data folder. Ensure EssentialsX is still installed and the folder name is exactly Essentials (case-sensitive on Linux).

"Economy manager not available" warning

Enable the economy module in config.yml (economy.enabled: true) and ensure Vault is installed. The economy import is skipped if the manager is missing.

"Invalid UUID in filename" errors

EssentialsX user data files must be named <uuid>.yml. If you have legacy files with usernames instead of UUIDs, rename them or those users will be skipped.

Missing worlds cause skipped homes/warps

The validator logs missing worlds. If you deleted a world since running EssentialsX, homes and warps in that world cannot be migrated. Restore the world or accept the loss.

Migration crashes mid-run

Individual user failures are caught and logged; the migration continues for remaining users. If the entire task throws an exception, the error message is sent to the command sender and the stack trace is printed to console. Fix the issue and rerun — already-migrated data is safe because the conflict resolver will skip duplicates on the next run.

Back locations not set

Back locations are only applied to online players. Ask players to log in before running the migration, or they will need to set their back location manually.

Post-Migration Checklist

Next Steps