mojang/minecraft-creator-tools/debug-addon

Debug a Minecraft Bedrock add-on

Validation catches most packaging and reference mistakes, so start there, then fall back to the runtime checklist for problems validation can't see. Keep going until validation reports zero errors, then tell the user what you changed.

1. Find the project folder

Validate the folder that contains behavior_packs/ and/or resource_packs/. A single pack folder (one with manifest.json) also works. If you can't tell which folder the user means, look for manifest.json files and ask if there's more than one candidate.

2. Run validation

Run the bundled summary script. Here and in later commands, <this-skill-folder> is the folder that contains this SKILL.md:

node "<this-skill-folder>/scripts/validate-summary.mjs" <project-folder>

It runs npx -y @minecraft/creator-tools@latest validate -i <folder> --json --force, sending the CLI's report files to a temporary folder. It then drops the dozens of "passed" entries, merges duplicates, checks that pack dependencies point at real packs (which the CLI doesn't), lists references to vanilla (minecraft:) content separately, and moves known false positives into a "likely noise" section. Exit code 0 means no errors; exit code 2 means validation couldn't run or found no project, so don't report success.

Why not call the CLI directly? You can (--json output has errors, warnings, recommendations totals and a projects[].items[] list), but three things trip people up:

• The CLI writes report files into an out/ folder in the current directory, which clutters the user's project. Pass -o <temp folder> to avoid it.
• Those reports double as a cache: without --force, re-validating returns the earlier results, so your fixes look like they did nothing.
• Most entries are testPass, info, or featureAggregate rows, which are not problems.

The MCP server's validateFile tool works too, but the script gives a cleaner result for whole projects.

3. Fix, in this order

1. Errors. These stop content from loading or being accepted.
2. Warnings. Treat them as real. An UNLINK warning pointing at your own namespace (for example geometry.demo.goblin not found) usually means something is invisible or missing in game.
3. Recommendations. Optional. Only change these when the user asks to upgrade or wants a clean report.

Check every ID in the "vanilla references" section: they're expected, because vanilla content lives outside the project, but a misspelled one such as minecraft:stik is a real bug. Leave "likely noise" alone unless the user wants a spotless report; Bedrock accepts those files as they are.

Look up fixes in references/validation-issues.md. For anything not listed there, open the docs: link the script prints; every check has a page in the Minecraft Creator Tools validation reference.

Missing pack icons are the most common error, and new projects created with Creator Tools don't include them. Create placeholders with:

node "<this-skill-folder>/scripts/make-pack-icon.mjs" <project>/behavior_packs/<pack> <project>/resource_packs/<pack> --color "#3C8527"

4. Re-run until there are no errors

Run the summary script again after each round of fixes. Stop when there are zero errors and no warnings you can explain as real problems. If a fix doesn't take effect, check you edited the file at the path the report shows (paths are relative to the project folder).

5. If it still doesn't work in game

Validation only checks files. For symptoms like an invisible mob, a purple-and-black texture, or a raw name such as entity.demo:goblin.name, work through references/runtime-symptoms.md. If that doesn't explain it, ask the user to turn on Minecraft's Content Log and paste what it shows; references/content-log.md explains how to turn it on and read it.

Raw names are the most common runtime complaint, because Creator Tools doesn't generate localization. Fix them all at once:

node "<this-skill-folder>/scripts/add-missing-names.mjs" <project-folder> --name "demo:goblin=Swamp Goblin"

It adds missing mob and block names to the resource pack's texts/en_US.lang and a minecraft:display_name to items that lack one, and never changes existing names. Pass --name for anything whose ID doesn't title-case into the right name; --dry-run shows what it would do.

To inspect content without Minecraft (for example on a Mac, where the game can't be launched from here), suggest the user run npx -y @minecraft/creator-tools@latest view -i <project-folder>. It opens a read-only browser view with 3D previews and keeps running until they stop it, so don't run it yourself as a blocking command.

Upgrading an old add-on

• npx -y @minecraft/creator-tools@latest fix setnewestminengineversion -i <folder> updates min_engine_version in every manifest. This one works reliably.
• fix setnewestformatversions may report updatedCount: 0 and change nothing. Update format_version in individual files by hand instead, and only when you know the file's schema didn't change between versions; re-validate after each change.
• fix randomizealluids is destructive: it breaks existing worlds that use the packs. Only run it when the user is copying a project to make a new one, and confirm first.

Run npx -y @minecraft/creator-tools@latest fix --list to see all fixes. Suggest committing to git (or making a copy) before running fixes, since they edit files in place.

Packaging for release

Once validation shows no errors:

npx -y @minecraft/creator-tools@latest exportaddon -i <project-folder> -o <output-folder>

This writes <project>.mcaddon containing every behavior and resource pack. Opening that file on a device with Minecraft installed imports it. Before exporting, check that each pack has a real pack_icon.png (not a placeholder, if the user cares) and a sensible header.version in manifest.json.

Things to avoid

• Don't accept the Minecraft EULA for the user. Validation, fixes, and export don't need it. If a command says the EULA wasn't accepted, ask the user to run npx -y @minecraft/creator-tools@latest eula themselves.
• Don't edit files under a Minecraft installation's vanilla packs. Only change the user's project.