Troubleshooting Custom Entities

Never guess why an entity is broken. Minecraft Bedrock includes a built-in error reporting tool called the Content Log that tells you the exact file, line, and component causing a failure. Before testing any add-on, open the game Settings, navigate to the Creator tab, and enable both Content Log File and Content Log GUI.

When you load into a world with these settings active, any JSON syntax errors, missing texture paths, or invalid component names will print directly to the screen for a few seconds. You can view the entire session history at any time by pressing Ctrl+H on Windows or by opening the Content Log History button found in the Creator settings menu.

If your custom entity does not show up in the autocomplete list for the /summon command, the game failed to register the behavior pack file. First, verify that the behavior pack is actually active on the world and that the file sits inside the BP/entities/ directory. Next, check the Content Log for syntax errors; a single missing comma or unclosed bracket causes the game to discard the entire file.

If the JSON is valid, inspect the description block. The identifier must include a custom namespace separated by a colon, and it cannot use the reserved minecraft namespace unless you are deliberately overriding a vanilla mob. Additionally, ensure that is_summonable is set to true, or the command parser will hide the entity.

{
  "format_version": "1.20.40",
  "minecraft:entity": {
    "description": {
      "identifier": "custom:stone_golem",
      "is_spawnable": true,
      "is_summonable": true,
      "is_experimental": false
    },
    "components": {
      "minecraft:type_family": {
        "family": [ "golem", "mob" ]
      },
      "minecraft:health": {
        "value": 40,
        "max": 40
      },
      "minecraft:physics": {},
      "minecraft:collision_box": {
        "width": 1.2,
        "height": 2.5
      }
    }
  }
}

When you can summon an entity and hear its sounds or see its shadow, but the model itself is completely invisible, the behavior pack is working while the resource pack link is broken. The client entity file in RP/entity/ connects the logic to the visuals, and every shortname you define in its description must be referenced in the render_controllers array.

Compare the identifier in your behavior pack with the identifier in your client entity file; they must match character for character. Then verify that your geometry, textures, and materials define a shortname (commonly 'default') and that a render controller uses those exact shortnames.

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "custom:stone_golem",
      "materials": {
        "default": "entity_alphatest"
      },
      "textures": {
        "default": "textures/entity/stone_golem"
      },
      "geometry": {
        "default": "geometry.stone_golem"
      },
      "render_controllers": [
        "controller.render.default"
      ],
      "spawn_egg": {
        "base_color": "#5A5A5A",
        "overlay_color": "#9E9E9E"
      }
    }
  }
}

An entity that spawns with a visible model but stands completely frozen is missing the core components required to process movement. In Bedrock's component-driven architecture, adding a behavior like random strolling does nothing on its own; the entity needs a navigation component to calculate paths, a movement type to dictate how it travels, and a base movement value to define its speed.

If an entity floats in mid-air and cannot be pushed, you have omitted the physics component. Always include the foundational movement stack alongside your behavior goals so the AI engine can execute the pathfinding requests.

{
  "format_version": "1.20.40",
  "minecraft:entity": {
    "description": {
      "identifier": "custom:stone_golem",
      "is_spawnable": true,
      "is_summonable": true
    },
    "components": {
      "minecraft:physics": {},
      "minecraft:movement": {
        "value": 0.25
      },
      "minecraft:movement.basic": {},
      "minecraft:jump.static": {},
      "minecraft:navigation.walk": {
        "can_path_over_water": false,
        "avoid_water": true
      },
      "minecraft:behavior.random_stroll": {
        "priority": 1,
        "speed_multiplier": 1.0
      },
      "minecraft:behavior.look_at_player": {
        "priority": 2,
        "look_distance": 8.0
      }
    }
  }
}

Dynamic entities use events to add and remove component groups at runtime, such as transforming a peaceful mob into a hostile one. When an event fires—either through a component trigger or the /event command—and the entity's behavior does not change, the failure is usually a typo between the event definition and the component_groups keys.

Verify that the string inside the add or remove object of your event matches the key under component_groups. Furthermore, check that you did not accidentally place your events block or component_groups block inside the main components block; all three must sit as sibling objects directly inside minecraft:entity.

Animations that refuse to play are typically disconnected in the client entity file. Just like textures and models, animations and animation controllers must be assigned a shortname in the description, and then triggered inside the scripts.animate array. If you define an animation shortname but omit the scripts block, the animation stays dormant.

When using Molang queries to control animation blending or transitions, watch the Content Log for runtime expression errors. In format versions 1.10.0 and above for client entities, spelling a query wrong—such as writing query.is_moving instead of the valid query.modified_distance_moved—will fail silently or throw a Molang error, locking the entity in its default pose.

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "custom:stone_golem",
      "materials": {
        "default": "entity_alphatest"
      },
      "textures": {
        "default": "textures/entity/stone_golem"
      },
      "geometry": {
        "default": "geometry.stone_golem"
      },
      "animations": {
        "walk": "animation.stone_golem.walk",
        "look_at_target": "animation.common.look_at_target"
      },
      "scripts": {
        "animate": [
          "look_at_target",
          { "walk": "query.modified_distance_moved" }
        ]
      },
      "render_controllers": [
        "controller.render.default"
      ]
    }
  }
}

Applies to Minecraft Bedrock 1.16.0 through 1.21+. Client entity definitions normally use format_version 1.10.0, while behavior pack entities should match your target game version. No experimental toggles are required for standard entity troubleshooting.

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