Troubleshooting Custom Blocks

Guessing why a block failed to load wastes hours. 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 schema validation during world load.

Before testing any block changes, go to Settings > Creator and enable both Content Log File and Content Log GUI. When you load into a world, any parsing error or missing resource reference will flash on the top of your screen, and you can press the assigned shortcut key to view the full log history.

If your block cannot be placed with the /setblock or /give commands and does not show up in the creative inventory, the behavior pack definition failed to register. The most common culprits are invalid JSON syntax (such as a trailing comma), an outdated format_version that does not support the components you wrote, or using the reserved minecraft: namespace in your identifier.

You should always validate your behavior file against a known working baseline. If this minimal block loads in your world, add your custom components back one by one until the Content Log flags the offending property.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "custom:debug_block",
      "menu_category": {
        "category": "construction"
      }
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 1.0
      }
    }
  }
}

When a block registers in the behavior pack but renders with a magenta-and-black checkerboard texture (or turns completely invisible), the resource pack chain is broken. In modern Bedrock, you can assign textures either inside RP/blocks.json for standard cubes or inside the behavior pack using the minecraft:material_instances component.

Regardless of which method you use, the texture shortname must exist in RP/textures/terrain_texture.json, and the file path pointed to by that shortname must match an actual PNG file on disk. A single typo anywhere in this chain breaks the material.

{
  "resource_pack_name": "custom_pack",
  "texture_name": "atlas.terrain",
  "padding": 8,
  "num_mip_levels": 4,
  "texture_data": {
    "debug_stone": {
      "textures": "textures/blocks/debug_stone"
    }
  }
}

When you apply the minecraft:geometry component to create a non-cube block like a chair, pillar, orbush, placing it next to standard blocks will often turn those adjacent block faces invisible, letting players see straight through the world. This happens because the engine assumes custom blocks are opaque 16x16x16 cubes and culls the touching faces of neighbor blocks to save rendering performance.

Furthermore, if your block uses transparent or semi-transparent pixels in its PNG file, those areas will render pitch black or white unless you change the render method. You must explicitly configure minecraft:material_instances to use a non-opaque render_method such as alpha_test or blend, which also instructs the engine to stop culling adjacent solid blocks.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "custom:statue"
    },
    "components": {
      "minecraft:geometry": "geometry.custom_statue",
      "minecraft:material_instances": {
        "*": {
          "texture": "statue_tex",
          "render_method": "alpha_test"
        }
      },
      "minecraft:light_dampening": 0
    }
  }
}

Blocks that change appearance or behavior based on states can fail to load if the state values are mismatched. Every state declared under description.states must be queried with the exact same data type inside your condition Molang strings. Mixing booleans (true/false) with integers (0/1) in a q.block_state() query will cause a Molang error.

Keep in mind that Bedrock enforces a strict limit on the total number of permutations a single block can have. Every additional state multiplies the total permutation count. If you combine too many states on one block, the Content Log will throw a registration error and drop the block entirely.

Applies to Bedrock Edition 1.20.60 and newer. Core components like minecraft:geometry, minecraft:material_instances, and minecraft:destructible_by_mining are stable and require no experimental toggles.

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