Troubleshooting

Troubleshooting and diagnostics

Use the installed release and real client/server logs to diagnose problems. A successful pack compilation or CI smoke test does not prove every client feature works in-game.

Home · Installation · Compatibility · Bedrock and Geyser

Plugin will not enable

1. Confirm the exact server version and the single matching VoxelCore distribution JAR in Compatibility.
2. Check the earliest VoxelCore startup error and its underlying cause. A later stack trace often hides the initial validation failure.
3. Validate content packs and YAML structure. VoxelCore deliberately fails a malformed content load rather than activating partially compiled content.
4. Confirm the Java runtime and Minecraft server software match the selected release family. Folia is not advertised as supported.

Items, blocks, or pack assets are missing

1. Check the pack location and YAML manifest in Content Packs.
2. Run /voxelcore admin content info and /voxelcore admin pack info.
3. Run /voxelcore admin pack validate [target] with an exact target from Compatibility.
4. Follow Resource Packs to build and deliver the current pack. For live Java delivery, verify that the player's client actually downloaded the updated ZIP from the reachable URL.
5. For custom blocks in existing worlds, retain block-allocations.yml and investigate mismatched allocation revisions before changing any carrier state.
6. For Bedrock, follow the separate publishing and client-reconnect procedure in Bedrock and Geyser. An on-disk export or publication receipt alone is not evidence that Geyser accepted a mapping.

UI font or inventory background looks wrong

• Verify the authored texture path, scale, ascent and placeholder spelling in UI, Fonts and Glyphs.
• Confirm the client loaded the latest Java or Bedrock pack, including generated fonts and UI textures.
• Bedrock Classic UI and Pocket UI do not have identical behavior; check which UI mode the client uses.
• For configurable popup backgrounds and spacing, follow Popup Tooltips.

Server restarts, reloads and recovery

• Use /voxelcore admin content reload for supported content changes rather than replacing live plugin JARs.
• VoxelCore's validated reload is atomic: when validation fails, the previously active runtime revision remains in use.
• Before reverting a plugin release, follow Backups, Upgrades and Rollback, especially when world/player data and custom allocation manifests are involved.

Reporting a problem

Include the exact Minecraft/server build, Java runtime, VoxelCore release JAR filename, addon versions if used, relevant log excerpt, current resource-pack target, client edition, reproduction steps and expected/observed behavior. Attach screenshots for visual differences. Use the issue tracker for public bugs, or the repository security policy for security vulnerabilities.