Debugging

Debugging

Use the built-in commands to establish which chunk, dimension, and lifecycle step failed before changing code. Chunkis tracing is designed around that evidence, not around guessing from a generic “failed to load chunk” message.

Commands

Command	Use
/chunkis debug on / off	enable or disable debug collection
/chunkis debug latest	show the most recent trace events
/chunkis debug suspects	list classified suspicious traces
/chunkis debug suspect <id>	inspect one suspect; timeline follows its events
/chunkis debug watch ...	watch a chunk, region, block, block entity, or entity; list, pending, and clear manage watches
/chunkis debug export latest / watched	export trace data for a report
/chunkis debug inspect neighbors / compare	inspect related chunks when a boundary or replacement is suspected
/chunkis debug remigrate	request migration-focused investigation/remediation from the debug command tree
/chunkis_storage_report	inspect CIS region and payload diagnostics
/durability_test	run the in-game durability scenario; /durability_test_stop stops it

What to inspect first

A block or block entity disappeared

1. Watch the affected chunk before reproducing.
2. Check whether the tracker recorded a Chunkis ownership claim.
3. Inspect the save trace for a rejected sparse/no-base payload or failed write.
4. Inspect the next load/restore trace and the stored payload report.

An invalid block-entity type ID is intentionally skipped during restore. That is a persisted-data compatibility issue, not a reason to retry the same payload indefinitely.

A chunk is wrong after reload

Check the source version, whether the payload has a persisted base/full baseline, and whether the load used tracker/cache/prefetch/disk. For v11, missing block entries are air; generated terrain remaining after restore indicates a restore-path defect, not an expected merge.

Entities duplicate or arrive late

Trace EntityReplayCoordinator and the chunk-full send path. Entity materialization is server-side and must happen once per restore operation; clients receive the normal vanilla entity/chunk synchronization afterward.

Migration is blocked

Read the migration report and source/backup paths. Do not manually delete MCA files to get past a failure: the coordinator uses verified backups and fails startup precisely to keep the authority transition safe.

Useful code locations

• fabric/.../command/ChunkDebugCommand.java — command tree.
• fabric/.../debug/trace/ChunkTraceStore.java — trace storage.
• fabric/.../debug/trace/PayloadWatchTracer.java — watched payload observations.
• fabric/.../command/report/CisPayloadDiagnosticsReader.java — storage report decoding.
• fabric/.../world/tracking/ownership/DeltaPersistenceGuard.java — invalid-save diagnostics.