Troubleshooting Custom Items in Minecraft Bedrock

Never guess why an item is broken. Minecraft Bedrock includes a built-in diagnostic tool called the Content Log that tells you the exact file, line number, and JSON key that failed to parse.

To turn it on, open Settings from the main menu, navigate to the Creator tab, and enable both Content Log File and Content Log GUI. When you load into a world with your add-on active, any syntax error, unrecognized component, or missing texture reference will flash on the top screen. You can also press the assigned shortcut key (or open the Creator settings in-game) to view the Content Log History.

If your item does not show up in the creative inventory or cannot be summoned with the /give command, the behavior pack definition failed to register. The most common cause is a JSON syntax error, such as a trailing comma or an unclosed bracket, which causes the parser to reject the entire file.

Another frequent issue is mixing legacy components with modern format versions. In modern Bedrock (format_version 1.20.50 and newer), item files are parsed strictly against the version declared at the top of the file. If you use an outdated component name or place an experimental component inside a stable format version without the matching world toggle, the item is skipped.

If the item works via /give but is hidden from the creative menu, check your menu_category object inside the description block. In modern schemas, assigning a category is handled directly inside description rather than through legacy creative_category components.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "my_pack:copper_coin",
      "menu_category": {
        "category": "items",
        "group": "itemGroup.name.ingot"
      }
    },
    "components": {
      "minecraft:icon": {
        "texture": "copper_coin"
      },
      "minecraft:max_stack_size": 64
    }
  }
}

When an item spawns in your hand as a flat magenta-and-black square or an invisible icon, the behavior pack loaded properly, but the resource pack failed to resolve the texture shortname.

In modern item definitions, the minecraft:icon component lives in the behavior pack file and points to a shortname (for example, copper_coin), not a direct file path. That shortname must be defined inside RP/textures/item_texture.json under the texture_data object. The path inside item_texture.json is relative to the root of the resource pack and omits the .png file extension.

Verify that your image is a valid, standard 8-bit RGBA PNG file. Make sure there are no uppercase letters in the folder names, file names, or shortnames, as Bedrock asset resolution can fail on case-sensitive platforms like Android and iOS.

{
  "resource_pack_name": "my_pack_rp",
  "texture_data": {
    "copper_coin": {
      "textures": "textures/items/copper_coin"
    }
  }
}

By default, an item without a display name component or localization entry shows up in the hotbar as item.my_pack:copper_coin.name or a similar raw string. You have two ways to fix this: hardcoding a string using the minecraft:display_name component in the behavior pack, or providing a translation key in your resource pack's .lang file.

Notice that modern data-driven items (format_version 1.16.100 and above) use a slightly different default translation key format than legacy vanilla items. While vanilla items often end with .name, custom items without an explicit display_name component frequently look for item.namespace:identifier in the language file, or whatever custom key you pass into the value field of minecraft:display_name.

Always check that your RP/texts/en_US.lang file is encoded in UTF-8 without BOM, and has no spaces around the equals sign.

item.my_pack:copper_coin=Copper Coin
item.my_pack:copper_coin.name=Copper Coin

The item schema in Minecraft Bedrock has gone through three major eras: the legacy 1.10.0 format (where icon and render offsets lived in a separate resource pack item file), the 1.16.100 transition (which moved icons into the behavior pack but required the Holiday Creator Features toggle), and the modern 1.20.50+ stable format.

A very common failure happens when creators copy components from an older 1.16.100 tutorial into a 1.20.50+ item file. Many components changed their syntax or were replaced entirely when moving to stable releases.

If you are building a 3D item using an attachable in the resource pack (RP/attachables/) rather than the minecraft:icon component, and the item renders invisible in your hand, check the identifier match first. An attachable automatically binds to a custom item when the description.identifier in the attachable JSON exactly matches the description.identifier in the behavior pack item JSON.

If the attachable logs a render controller or material error, check that you included the default material, texture, and geometry keys inside the attachable description, and that the geometry identifier in your model file starts with geometry. as required by modern schemas.

Applies to Bedrock Edition 1.20.50 and newer. Modern stable item components do not require experimental toggles; custom scripting components require @minecraft/server in your behavior pack manifest.

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