Support Scope and Troubleshooting
This page summarizes the supported Minecraft Java Edition profiles, explains the boundary between CLI/parser verification and live in-game verification, lists all CLI exit codes, and provides step-by-step solutions for common errors.
1. Supported Minecraft Java Edition Profiles
Section titled “1. Supported Minecraft Java Edition Profiles”Run nbtcli capabilities at any time to inspect the registered command list and the declared support matrix for each pinned Minecraft DataVersion profile:
.\nbtcli.exe capabilities| Profile | DataVersion | Dimension Layout | Item Schema | Text Component Schema | Pack Layout |
|---|---|---|---|---|---|
java-1.20.4 | 3700 | java-dimensions-directory | java-item-tags-1.20.4 | java-text-json (v1) | java-pack-plural |
java-1.21 | 3953 | java-dimensions-directory | java-item-components-1.20.5 | java-text-json (v1) | java-pack-singular |
java-1.21.5 | 4325 | java-dimensions-directory | java-item-components-1.21.5 | java-text-nbt (v1) | java-pack-singular |
java-26.1-snapshot-6 | 4774 | java-dimensions-namespaced | java-item-components-26.1-snapshot-6 | java-text-nbt (v2) | java-pack-singular |
Reading the capabilities Output
Section titled “Reading the capabilities Output”For each profile, capabilities reports five operations (read, extract, plan, write, recover) across six facets (layout, itemSchema, textSchema, commandGrammar, compression, packLayout):
- Readable does not automatically imply writable: Never assume a world format can be modified just because
getorlistcan read it. The planner and writer check whether the specific target role, component schema, and profile are supported before creating or applying a plan. - Parser Verification vs. Live In-Game Verification:
validate,scan,plan, andapplyverify binary NBT/region framing, JSON syntax, SHA-256 preimages/postimages, and schema rules at the CLI level.- Passing CLI validation is not a substitute for loading the world inside the Minecraft Java Edition client. In-game visual rendering, custom font spacing, and live command execution behavior that have not yet been tested in the running game remain pending live in-game verification (
尚待實機驗證) — always verify your translated or edited world copy inside Minecraft before distributing a map.
2. Supported World Text Roles (21 Roles)
Section titled “2. Supported World Text Roles (21 Roles)”When running scan, extract, validate, convert, or translate start, the --types option can filter by any combination of the 21 supported text roles:
- Blocks & Signs:
Sign,HangingSign,ContainerName,CommandBlock - Books & Lecterns:
Book,LecternBook,Title,Author - Items & Entities:
ItemName,ItemLore,ArmorStand,EntityName,TextDisplay - World & UI State:
BossBar,ScoreboardTeam,ScoreboardObjective - Datapacks & Resources:
McFunction,Advancement,CommandStorage,LangKey,TranslationKey
3. Exit Codes Reference
Section titled “3. Exit Codes Reference”Every invocation returns a deterministic exit code alongside the JSON response on stdout. When an exit code is non-zero (success: false), inspect error.code, error.message, and error.details for the exact reason.
| Exit Code | Category | Meaning | Recommended Action |
|---|---|---|---|
0 | Success | The command completed normally (including a valid search with zero matches or a verified no-op). | Proceed to the next step in your workflow. |
1 | Internal Failure | An unexpected internal error occurred. | Inspect error.code and error.details; verify the world status before retrying. |
2 | Invalid Arguments | Unknown command or flag, missing required value, repeated option, or incompatible selector. | Run nbtcli help <command> to check exact flag names. No files were changed. |
3 | Conflict or Stale State | The world or session changed since the plan/page was created, the node address is ambiguous, or an operation ID was reused with different input. | Re-scan or export the latest session revision and generate a fresh plan. |
4 | Unsupported Format or Incomplete Scope | The target world uses an unsupported DataVersion/profile feature, or selected sources could not be completely discovered. | Check nbtcli capabilities and narrow the scan/edit scope with --path, --dimension, or --types. |
5 | File, Access, or Validation Error | Missing file, locked world file, malformed NBT/JSON input, or pre-commit preparation failure. | Ensure Minecraft is closed, verify the file path, or restore damaged files from a backup. |
6 | Resource or Timeout Limit | Input size, slot count, node depth, output size (64 MiB max), or regex match time (100 ms) exceeded safety limits. | Filter by --dimension, --region, or --path, reduce --page-size, or simplify --match-pattern. |
7 | Recovery Required | A write operation was interrupted or encountered an I/O error after committing began. | Do NOT open the world in Minecraft. Keep the returned planHash and stateRoot, run nbtcli status, then run nbtcli recover. |
8 | Rolled Back | Recovery rolled the world back to its verified pre-edit state rather than applying the changes forward. | Your original world bytes are restored. Create a new plan if you wish to apply changes again. |
130 | Cancelled | The operation recorded a cancelled receipt. | If cancelled during a write, run status and recover with the plan hash before using the world. |
4. Common Troubleshooting Scenarios
Section titled “4. Common Troubleshooting Scenarios”Scenario A: World File Is Locked or Access Is Denied (Exit Code 5)
Section titled “Scenario A: World File Is Locked or Access Is Denied (Exit Code 5)”Symptom: scan, backup, or apply fails with exit code 5 (IO_ERROR or ACCESS_DENIED).
How to Resolve:
- Close the Minecraft Java Edition client, integrated server, or dedicated server completely.
- Close any other tools inspecting the same world folder (such as NBT viewers, map renderers, or archive managers).
- Re-run the command on your world copy.
Scenario B: Write Interrupted — RECOVERY_REQUIRED (Exit Code 7)
Section titled “Scenario B: Write Interrupted — RECOVERY_REQUIRED (Exit Code 7)”Symptom: apply or recover returns exit code 7 (RECOVERY_REQUIRED).
How to Resolve:
- Do not open the world in Minecraft.
- Copy the
planHashandstateRootfrom the JSON output. - Run
nbtcli status <world> --plan-hash <hash> --state-root <stateRoot>to inspect the journal state. - Run
nbtcli recover <world> --plan-hash <hash> --state-root <stateRoot> --world-offlineto finish the planned write, or add--rollbackto restore the original pre-edit files (returns exit code8).
Scenario C: World Modified Externally After Creating a Plan or Session (Exit Code 3)
Section titled “Scenario C: World Modified Externally After Creating a Plan or Session (Exit Code 3)”Symptom: apply or translate submit fails with exit code 3 (CONFLICT).
Why It Happens: One or more world files changed on disk after your patch-plan or translation session snapshot was created. NBTExplorerCLI refuses to overwrite changed files with stale plans.
How to Resolve:
- If an edit plan is stale: Re-run
get --typesandset/planon the current world files to generate a fresh plan. - If a translation session snapshot is stale (
repair: "start-new-session"): Start a new session on the updated world copy; follow the translation memory example with the new session ID, its full slot hash, the previous session ID, and the glossary version.
Scenario D: Corrupted Region/NBT File or Unsupported Format (Exit Code 4 or 5)
Section titled “Scenario D: Corrupted Region/NBT File or Unsupported Format (Exit Code 4 or 5)”Symptom: scan or validate reports coverageComplete: false with exit code 4 (unsupported profile/feature) or exit code 5 (malformed/corrupt file, such as a zero-byte region file or invalid JSON in a datapack).
How to Resolve:
- Run
nbtcli validate <world>and inspect the per-source diagnostics in the JSON output to see which exact relative file path failed. - If a single file is damaged and you have a verified backup, restore that specific file using
nbtcli restore <world> --manifest-hash <hash> --path <relative-path> --apply --world-offline. - If you only need to translate or edit healthy dimensions or specific files, scope your command using
--dimension,--region,--path, or--typesto exclude the damaged or unsupported file.
Scenario E: Resource Budget or Regex Timeout Exceeded (Exit Code 6)
Section titled “Scenario E: Resource Budget or Regex Timeout Exceeded (Exit Code 6)”Symptom: Command exits with code 6 (RESOURCE_LIMIT or PATTERN_TIMEOUT).
Why It Happens: To prevent out-of-memory crashes or runaway regular expressions, NBTExplorerCLI enforces a 64 MiB artifact/output ceiling, a 100,000-slot session limit, a 256-segment node depth limit, and a 100 ms regex timeout.
How to Resolve:
- Narrow the target scope with
--dimension,--region,--path, or--types. - When starting or exporting a translation session, lower
--page-sizeor--page-bytes. - Simplify complex
--match-patternregular expressions.