Updating EssentialsC

Before You Update

While EssentialsC includes safety mechanisms, always follow these precautions:

• Back up your data — Copy plugins/EssentialsC/database/ and plugins/EssentialsC/config.yml to a safe location. The built-in backup system can also create one on demand with /essc backup.
• Check release notes — Major versions may introduce breaking changes. Review the GitHub Releases page for migration notes.
• Verify server compatibility — Ensure your server software supports the new API version. EssentialsC 4.1.7 targets api-version: '1.21'.
• Stop the server — Never hot-swap plugin jars while the server is running. File locks can corrupt SQLite databases.

Automatic Config Migration

EssentialsC ships with a ConfigMigrator that runs automatically on every startup. It ensures your config files stay compatible without manual intervention.

How it works

• Version tracking — Both config.yml and commands.yml contain a config-version field. The current version is 1 for both files.
• Missing key injection — The migrator loads the default config from the jar and adds any missing keys to your existing files. Your custom values are never overwritten.
• Version migrations — When config-version is older than the current version, structured migration routines run. Currently v0→v1 migrations exist but are empty (reserved for future schema changes).
• Dirty detection — Files are only saved if changes were actually made, preventing unnecessary disk writes.

Migration debug output is visible in console when debug: true is set in config.yml:

[EssentialsC] config.yml — added missing key: economy.minimum-transaction
[EssentialsC] config.yml updated from version 0 to 1

Update Procedure

What Reloads Automatically

When you run /essc reload, the following managers and systems are hot-reloaded without restarting:

• Configuration — config.yml reloaded; economy module can be enabled/disabled dynamically
• Languages — All JSON language files and help command outputs reloaded
• TPA system — Cooldown, warmup, timeout, and blocked worlds updated
• Homes — Max homes, cooldown, warmup, GUI mode, and blocked worlds updated
• Spawn — First-join teleport, respawn, bed override, and particles/sounds updated
• Back — Warmup, cooldown, and movement cancellation updated
• Kits — Kit definitions reloaded from kits.yml
• Scoreboard — Sidebar configuration and PlaceholderAPI placeholders refreshed
• Vanish — Tab hide, night vision, mob target, and collision settings updated
• Nicknames — Length limits, color/format permissions, blacklist, and tab update settings reloaded
• Shop — Category files, prices, and GUI templates reloaded
• Auction House — Duration, price limits, blacklists, and GUI items reloaded
• Warp — Cooldown, warmup, blocked worlds, and per-player limits updated
• AFK — Timeout, kick settings, tab placeholder, and damage prevention updated
• Chat — Slow mode, caps threshold, mentions, link filtering, and LuckPerms formatting reloaded
• RTP — Per-world settings, blocked biomes, and GUI options updated
• TAB — LuckPerms prefix/suffix formatting refreshed for all online players
• Rules — rules.txt reloaded
• Schedules — Automated tasks reloaded from schedules.yml
• MOTD — motd.txt reloaded
• Sell GUI — Title, size, fill material, and border material updated
• Fly — Persistent mode and restore-on-join settings reloaded

Database Compatibility

EssentialsC uses SQLite for all persistent storage. Database schemas are designed to be forward-compatible:

• homes.db — Stores home locations with world UUID, name, coordinates, yaw, and pitch
• economy.db — Stores player balances as DECIMAL with username and UUID
• auction.db — Stores listings, expired items, buy history, and sell history
• kits.db — Tracks kit cooldowns, one-time claims, and first-join status
• nicks.db — Stores MiniMessage-formatted nicknames with unique constraints
• shop.db — Logs shop transactions when shop.log-transactions: true

If a database file becomes corrupted, restore from the backups/ folder. EssentialsC never modifies existing table structures destructively — new columns are added via migration scripts if needed in future versions.

Rollback Procedure

If an update causes issues, roll back safely:

1. Stop the server
2. Replace the new EssentialsC.jar with the previous version's jar
3. Restore plugins/EssentialsC/database/ from your pre-update backup
4. If config migration caused issues, restore config.yml and commands.yml from backup, then manually re-add any new keys from the default config
5. Start the server

Built-In Backup System

EssentialsC includes an automatic backup system that archives your entire plugin data folder:

• Automatic shutdown backups — Enabled by default (backup.on-shutdown: true). Creates a zip archive every time the server stops.
• Retention policy — backup.keep-last: 10 controls how many backups are retained. Older backups are deleted automatically.
• Manual backups — Run /essc backup to create a backup on demand. The operation is async and notifies you when complete.
• Backup management — Use /essc backup list to view all backups with size and date, and /essc backup delete <name> to remove specific archives.

Backups are stored in plugins/EssentialsC/backups/ as timestamped zip files.

Diagnostic Dumps

If an update causes unexpected behavior, generate a diagnostic dump to share with support:

/essc dump

This collects a comprehensive system report and uploads it to https://dumps.godlycow.org/. The dump includes:

• Environment — TPS (1m/5m/15m), memory usage, CPU cores, online mode, player count, Folia/Paper detection, feature flags
• Hooks — Vault, LuckPerms, PlaceholderAPI, DiscordSRV, Floodgate, TAB, SkinRestorer status
• Config — Full sanitized config.yml with passwords, tokens, and secrets redacted automatically
• Economy — Total accounts, money in circulation, top 5 balances, zero-balance count
• Punishments — Active bans, IP bans, mutes with reasons, banners, and expiration times
• Databases — File sizes, user count, ban/mute/fly records
• Managers — Boolean status of all 18 managers (economy, homes, warps, auction, etc.)
• Plugins — Full plugin list with conflict detection for EssentialsX, CMI, and EssentialsX sub-plugins

Troubleshooting Updates

Plugin fails to enable after update

The CrashHandler catches startup exceptions, prints a formatted error block to console, notifies online ops/admins, and disables the plugin gracefully. Check the console for the exception class and message. Common causes:

• Missing or incompatible dependency (Vault, LuckPerms)
• Corrupted database file — restore from backup
• Config syntax error — validate YAML with an online parser
• Server software mismatch — ensure Paper/Spigot/Folia 1.21+

Config values reset after update

This should not happen — the ConfigMigrator only adds missing keys. If values were reset, you likely replaced config.yml with the default from the jar. Restore from backup.

Database "locked" errors

SQLite does not support concurrent access across processes. Ensure the server is fully stopped before copying database files. Never edit .db files with external tools while the server is running.

PlaceholderAPI expansions missing after update

The FirstRunHandler only runs once (tracked by .setup-complete). If you deleted PlaceholderAPI expansions, reinstall them manually: /papi ecloud download Vault Player Server Statistic LuckPerms.

Economy stopped working after reload

Check that economy.enabled: true is still present in config.yml. The reload command can dynamically disable economy if the config changed. Run /essc reload again after correcting the config.

Version History

EssentialsC follows semantic versioning. Track releases and changelogs:

Next Steps