Operations and Troubleshooting
Documentation baseline: VoxelCore
mainat452b569· 14 September 2026.
Repository: https://github.com/VoxelHorizons/VoxelCore
Plugin will not enable
Check the first SEVERE VoxelCore error, not only the final disable line. Startup intentionally aborts for unsupported platforms, malformed content, failed inheritance, invalid render allocation state or platform preflight failure.
Expected successful endpoint:
VOXELCORE_READY revision=1 items=<count> platform=<version>
Unsupported Minecraft version
VoxelCore selects a platform provider explicitly. Exact-only providers such as 1.21.4 and 26.2 reject other releases. Install the correct distribution and do not assume a newer server is compatible merely because it starts with a similar API.
Reload fails
Use:
/voxelcore admin content reload
A failed reload is designed to leave the previous revision active. Fix the reported authoring/platform error and reload again; do not delete known-good runtime files as a first response.
Common causes include missing parents, cycles, undeclared cross-pack dependencies, missing/invalid model references, malformed structured model keys and definitions that cannot be represented by the active adapter.
Item is missing from item list
Check the compiled bound value with:
/voxelcore admin item info <content-id>
As of PR #16, unbound definitions are intentionally omitted from item list. This is expected for inheritance-only bases.
Item does not identify
Use the held-item command for a player:
/voxelcore admin item identify
or the console-safe round-trip test:
/voxelcore admin item verify <content-id>
The verify success marker is:
VOXELCORE_ITEM_VERIFY_OK ...
Stored malformed/corrupt ContentID metadata is handled defensively and should not crash ordinary identification.
Pack target not auto-selected
Pack commands auto-select only for an exact JavaPackTarget. Specify one explicitly, for example:
/voxelcore admin pack validate mc-26.2
Rendering changes unexpectedly after deleting allocations
render-allocations.yml is persistent allocation history. Removing it can reassign numeric CMD or structured indices. Restore the manifest from backup/versioned server data where possible rather than treating it as disposable cache.
Config migrated
Look for config.yml.old, .old.1, etc. Current migration preserves existing values and adds new defaults. Do not copy an old schema version back over the migrated file without understanding the change.