Troubleshooting

Creating Add-Ons for Bedrock Minecraft is a relatively straightforward process once you get the hang of it. The first time is usually a frustrating, bug-prone process. This document contains some tips and tricks for fixing those dastardly bugs, as well as best practice information.

Please read the whole page, before jumping into troubleshooting tips for a specific domain.

Reload Minecraft

First, you should always reload Minecraft. That means fully closing the game and then reopening it. This can catch many errors, especially those related to assets that are accessed via a filepath, such as textures or loot tables.

The Environment

The best way to prevent nasty bugs is by working in the right environment. You should review the software preparation document for editor recommendations. The most important part is getting a JSON-linter, (or using an online json-linter), and storing your packs in development_behavior_packs and development_resource_packs.

If you have your add-ons in the normal folders (minecraftWorlds, behavior_packs, etc.), you can run into "pack caching" issues, where you edit the files in one location, but the game is still using the old, cached files. Use the development folders!

Content Log (Essential!)

Use the Content Log! Content log is the best tool you have for debugging your add-ons. Please don't skip this step!

The 'Content Log' is a list of issues found in your pack. Minecraft will generate this list every time you load your world. It can catch issues such as:

Wrong texture path
Wrongly spelled component
Incorrect json structure
Syntax errors
Missing dependencies

Errors are not cleared between runs, so the errors you see in the content log may be old errors from prior runs. Always check the latest errors after reloading your world.

Enabling the Content Log

You must enable the Content Log by editing the options.txt file.

Important: Close Minecraft completely before editing options.txt. Changes might be overwritten if the game is running.

Find the options.txt file located inside the minecraftpe folder, which is usually inside your main com.mojang folder. (Refer to the Project Setup page for help finding the com.mojang folder if needed).

Open options.txt with a text editor and find or add the following lines, setting the values to 1:

options.txt (relevant lines)

... (other settings) ...content_log_file:1 # Set to 1 to enable file logging (can use lots of storage!)content_log_gui:1  # Set to 1 to enable on-screen log... (more settings) ...

content_log_file:1 enables saving the log to a file (useful for long logs, but can consume storage over time).
content_log_gui:1 enables the on-screen log visible when loading worlds or during gameplay if errors occur.

Save the file, then restart Minecraft. The content log should now be active.

Content Log File Location

If you enabled file logging (content_log_file:1), the log is saved as a .txt file inside a logs folder within your Minecraft data directory:

Windows: C:\Users\USERNAME\AppData\Local\Packages\Microsoft.MinecraftEducationEdition_8wekyb3d8bbwe\LocalState\logs\ (Replace USERNAME)
Android: /storage/emulated/0/Android/data/com.mojang.minecraftedu/files/games/com.mojang/logs/

This file can be very helpful for reviewing many errors that might scroll off the screen too quickly in the GUI log.

Using Vanilla Resources

You should download the vanilla resource and behavior pack. These official packs contain all the default Minecraft assets and behaviors. You can compare your files against the vanilla files if you have any issues or want to see how Mojang implements features!

Download Vanilla Packs (Microsoft Docs)

JSON-Schemas

JSON-Schemas are a valuable tool for file validation, especially when using code editors like VS Code. They define the expected structure and valid values for specific JSON file types used by Minecraft. Using schemas can help you catch errors *before* you even load the game.

Learn more about JSON-Schemas

Troubleshooting Your Add-On

Below are common areas where issues arise. Check the Content Log first, then look for specific guides related to these topics if you're stuck.

Entities: Issues with models, textures, animations, behaviors, spawn rules, loot tables.
Items: Problems with textures, components, crafting recipes, functionality.
Blocks: Issues related to textures, models, states, components, loot tables.

Remember to check the official Minecraft Creator Documentation and the community Discord for further help.