Upgrading and Backups

Backups, upgrades and rollback

Keep a restorable backup before installing or upgrading VoxelCore. This is particularly important for worlds using persistent custom block allocations, item identities and Geyser mappings.

Home · Installation · Compatibility · Troubleshooting

Before updating

1. Stop the Minecraft server and any separately hosted Geyser instance that you plan to update.
2. Back up the current plugins/VoxelCore/ directory, particularly config.yml, the content/ packs, generated allocation files such as render-allocations.yml, glyph-allocations.yml and block-allocations.yml, and the current generated resource packs.
3. Back up the worlds and relevant player/item data with a consistent server backup procedure.
4. Keep copies of the currently running VoxelCore plugin JAR and any installed VoxelCore Geyser extension JAR.
5. Record the exact Paper/Minecraft version, current resource-pack target, Geyser version and plugin versions involved in the upgrade.

Do not remove or regenerate an existing world's allocation manifest just to resolve a conflict. Doing so can make pre-existing custom blocks or items point at different representations.

Upgrade procedure

1. Choose exactly one matching server JAR from the intended GitHub release. Consult Compatibility rather than mixing JAR families.
2. Replace the old VoxelCore server JAR while the server is stopped, removing older duplicate VoxelCore distribution JARs from plugins/.
3. If updating the optional Geyser extension, replace its JAR at the actual Geyser host and keep Geyser's pack/mapping files in the matching revision set.
4. Start the server and review early VoxelCore startup messages. VoxelCore's documented config migration writes config.yml.old variants as needed and retains existing values; do not assume this replaces an external backup.
5. Use /voxelcore admin content info, /voxelcore admin pack info, and appropriate pack validation/build commands to check the active content and outputs. For changed content, build Java first so Bedrock conversion sees the current render and block allocations.
6. Reconnect a Java player, and a Bedrock player where supported, to validate representative items, blocks, glyphs and inventories before returning the server to normal traffic.

Rolling back

1. Stop the server; do not simply put an older JAR on top of potentially migrated data and assume compatibility.
2. Restore the matching backed-up plugin JAR, plugins/VoxelCore/ data, resource packs and (where appropriate) world/player backup.
3. When Bedrock is involved, restore the matching set of Geyser pack and mapping files together; restart Geyser and reconnect clients. See Bedrock and Geyser.
4. Verify content IDs, allocation persistence, basic inventory behavior and server logs before allowing new changes.

For a fatal startup error, missing carrier model, or inconsistent client pack, see Troubleshooting and include exact version/build evidence in a report. Never share secrets, access tokens or private world/player data in public issues.