Troubleshooting Add-on Errors and Missing Assets

The single most important tool for Bedrock add-on development is the Content Log. By default, Minecraft hides all JSON parsing errors, schema violations, and missing asset warnings from the player. To turn them on, open the main Settings menu from the title screen or pause menu, scroll down to the Creator tab, and enable both Content Log File and Content Log GUI.

With the GUI toggle enabled, any error encountered while loading a world or running a pack will print directly onto the top of your screen for a few seconds. You can also press the designated shortcut key (or open the Creator settings in-game) to view the Content Log History, which holds every warning and error since the session started. If you enabled the file toggle, the game writes a persistent plain-text log into your `com.mojang/logs` directory, which is essential if an error causes the game client to crash to the desktop before you can read the screen.

Errors are categorized by subsystem, such as `[Blocks]`, `[Entities]`, `[Json]`, or `[Molang]`, and by severity (`Inform`, `Warning`, `Error`). While developing, treat every `[Json][error]` and schema violation as a blocker: when the parser hits a syntax error in a file, it usually abandons the rest of that file entirely.

If your add-on does not show up in the Available Behavior Packs or Available Resource Packs lists inside the world settings, the game could not parse your `manifest.json` or the pack is sitting in the wrong folder. Development packs belong in `development_behavior_packs` and `development_resource_packs` inside your `com.mojang` folder, not the standard `behavior_packs` folder. Placing packs in the development folders tells Minecraft to reload their contents every time you exit and re-enter a world, bypassing the internal cache.

Every manifest requires two distinct Version 4 UUIDs: one inside the `header` object and a completely different one inside the `modules` array. If you copy a manifest from an existing pack and forget to generate new UUIDs, Minecraft will see a duplicate identifier and either refuse to load your new pack or overwrite the old one in the UI. Furthermore, if you use a Behavior Pack alongside a Resource Pack, the UUIDs in the Behavior Pack must never match the UUIDs in the Resource Pack unless you are deliberately linking them inside the `dependencies` block.

Always check the `min_engine_version` array inside the `header`. This three-number array (such as `[1, 20, 80]`) tells the game which baseline engine behaviors to apply to your pack. If it is missing in modern format versions, or set higher than the version of Minecraft you are currently running, the pack will fail to register.

{
  "format_version": 2,
  "header": {
    "name": "Example Behavior Pack",
    "description": "A valid manifest with unique UUIDs.",
    "uuid": "a1839c70-2d91-4f83-9b24-110293847561",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "b2940d81-3e02-4a94-8c35-221304958672",
      "version": [1, 0, 0]
    }
  ]
}

While older versions of Bedrock used a forgiving JSON parser that sometimes ignored trailing commas or unquoted keys, modern `format_version` schemas enforce strict validation. A trailing comma after the last item in an object or array, a missing closing brace, or using single quotes instead of double quotes will cause the entire file to be rejected. Always write your files in a code editor that highlights JSON syntax errors before you launch the game.

Beyond raw syntax, the Content Log frequently flags schema errors where the JSON is valid, but the data does not match what Minecraft expects. A classic mistake is mismatching the `format_version` at the top of a block, item, or entity file with the components inside it. For example, attempting to use modern item components in an item file declared with an outdated `format_version` like `1.10.0` will cause the parser to throw an unknown component error.

Another frequent silent failure is an identifier mismatch. In custom blocks, items, and entities, the `identifier` string declared inside the `description` object must include a custom namespace (anything other than `minecraft:`, such as `wiki:custom_stone`) and must match the identifier you reference in recipes, loot tables, and commands. While the file name itself does not strictly have to match the identifier, keeping them identical makes tracking down `[Json][error]` messages in the Content Log much faster.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:custom_slate"
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.0
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 6.0
      }
    }
  }
}

Visual bugs in a Resource Pack almost always trace back to broken indirection. Bedrock does not link an entity, block, or item directly to a `.png` file path inside its main definition. Instead, it uses a chain of shortname references mapped through bridge files like `RP/textures/terrain_texture.json` (for blocks) and `RP/textures/item_texture.json` (for items). If any link in that chain has a typo, you will see the purple and black missing texture checkerboard, or an invisible model.

For blocks and items, verify that the shortname you assigned in your `minecraft:material_instances` or `minecraft:icon` component exists as a key inside `terrain_texture.json` or `item_texture.json`. Next, check the file path attached to that key: paths are always relative to the root of the Resource Pack (for example, `textures/blocks/custom_slate`), use forward slashes, and omit the `.png` extension. Finally, check that the image file actually exists at that exact path and is saved as standard 8-bit RGBA PNG, not a renamed JPEG or a CMYK file.

For custom entities and complex blocks, if the shadow appears on the ground but the model itself is completely invisible, the problem is usually the geometry identifier or the render controller. Open your `.geo.json` file in `RP/models/entity/` or `RP/models/blocks/` and check the `identifier` inside the `description` block—it must start with `geometry.`. That exact string must match what you wrote in your client entity file (`RP/entity/`) or block `minecraft:geometry` component.

When a Molang expression in an animation controller, render controller, or particle file fails, the Content Log will prefix the message with `[Molang][error]`. The most common cause is querying a variable or property on an entity that does not have it initialized, or misspelling a query function (for example, writing `query.is_on_ground` in a context where the entity does not exist). Remember that client-side Molang scripts in the Resource Pack cannot directly read server-side Behavior Pack variables unless you sync them using entity properties or synced data.

If you are using the TypeScript or JavaScript Script API in your Behavior Pack and your scripts never run, first check the `manifest.json` modules array. A script module must have its `type` set to `script`, `language` set to `javascript`, and an `entry` field pointing to the exact relative path of your main script file (such as `scripts/main.js`).

Second, verify your module dependencies in `manifest.json`. The version of `@minecraft/server` declared in your `dependencies` array must be supported by the version of Minecraft you are running. If you specify a `-beta` version of a script module, the pack will throw a dependency error on load unless the Beta APIs experimental toggle is explicitly turned on in the world settings. Stable version numbers (like `1.11.0`) do not require the toggle, but cannot call methods marked as beta.

Applies to all modern Bedrock versions (1.20.x and 1.21.x). The Content Log and standard JSON validation require no experimental toggles. Testing `-beta` Script API modules requires the Beta APIs experimental toggle in World Settings.

Read out of the game itself, so the ids match the version you are building for.