# Operations and Troubleshooting


> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.  
> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](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:

```text
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:

```text
/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:

```text
/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:

```text
/voxelcore admin item identify
```

or the console-safe round-trip test:

```text
/voxelcore admin item verify <content-id>
```

The verify success marker is:

```text
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:

```text
/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.