Home A - Z
Page Index

Blame

e23584 Dan Alexander 2026-09-14 10:46:55
Add company wiki standards and VoxelCore docs This change establishes the shared company knowledge structure, governance, engineering, security, and incident/change standards. It also adds the VoxelHorizons product tree with a complete VoxelCore documentation set covering architecture, operations, authoring, version support, resource pack compilation, runtime reloads, and testing/release workflows.
1 
# Operations and Troubleshooting
2
3
4
> **Documentation baseline:** VoxelCore `main` at `452b569` ยท 14 September 2026.
5
> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)
6
7
8
## Plugin will not enable
9
10
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.
11
12
Expected successful endpoint:
13
14
```text
15
VOXELCORE_READY revision=1 items=<count> platform=<version>
16
```
17
18
### Unsupported Minecraft version
19
20
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.
21
22
## Reload fails
23
24
Use:
25
26
```text
27
/voxelcore admin content reload
28
```
29
30
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.
31
32
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.
33
34
## Item is missing from `item list`
35
36
Check the compiled `bound` value with:
37
38
```text
39
/voxelcore admin item info <content-id>
40
```
41
42
As of PR #16, unbound definitions are intentionally omitted from `item list`. This is expected for inheritance-only bases.
43
44
## Item does not identify
45
46
Use the held-item command for a player:
47
48
```text
49
/voxelcore admin item identify
50
```
51
52
or the console-safe round-trip test:
53
54
```text
55
/voxelcore admin item verify <content-id>
56
```
57
58
The verify success marker is:
59
60
```text
61
VOXELCORE_ITEM_VERIFY_OK ...
62
```
63
64
Stored malformed/corrupt ContentID metadata is handled defensively and should not crash ordinary identification.
65
66
## Pack target not auto-selected
67
68
Pack commands auto-select only for an exact `JavaPackTarget`. Specify one explicitly, for example:
69
70
```text
71
/voxelcore admin pack validate mc-26.2
72
```
73
74
## Rendering changes unexpectedly after deleting allocations
75
76
`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.
77
78
## Config migrated
79
80
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.