---
title: "Head validation"
url: /docs/en-us/avatar/dynamic-heads/validate
last_updated: 2026-06-17T23:57:42Z
description: "In-depth details on how Roblox validates head assets"
---

# Head validation

> **Info:** This content is for creators who intend to create character heads designated for the Marketplace, or any character heads that support assets from the Marketplace.

Roblox runs a rigorous validation to ensure the asset being uploaded to the Marketplace is compatible with all other assets on the Marketplace. For heads, validation primarily ensures that the head asset includes:

- A correctly **configured cage** — to wear clothing and accessories.
- Correctly configured **facial animation poses** — to perform basic universal expressions, such as blinking and smiling.

The primary validation check for heads [uses the cage to detect facial animation](#facial-animation-detection). See below for a reference of how validation processes, as well as [common issues](#common-issues).

> **Warning:** Validation also checks for other issues, such as poor caging or missing required FACS poses. For more information, see [common issues](#common-issues).
> **Info:** **Avatar Setup recommendation**
>
> [Avatar Setup](/docs/en-us/avatar-setup.md) is an automated tool that automatically generates components for your avatar character, **including the head cage and facial animation** required for Marketplace character models. You can save time by submitting character models without avatar components into the Avatar Setup tool and modifying the output.
>
> You can test and refine your Avatar Setup output by using the Avatar setup tool previews. You can even download your output as a `.gltf` and adjust the FACS or cage data in your DCC tools.
>
> You can alternatively manually modify your own cages and FACS animations within your DCC tools, which may require more time or additional iteration in your workflow, such as weight-painting adjustments, to ensure it meets Marketplace policies.
>
> To submit issues or feedback regarding the avatar auto setup tool, submit a [bug report](https://devforum.roblox.com/c/bug-reports/10).
## Facial animation detection

One of the primary dynamic head validation checks verifies if your head asset has **visually discernable** animations. To achieve this, the validation tool uses the head cage to ["project" landmarks](#landmark-projection) onto your base mesh.

After these landmarks created, validation [tests various face animation poses](#facial-animation-detection) to ensure that these landmarks move and deform appropriately. Validation succeeds when it detects appropriate movement of the landmarks for eyes closed, mouth open, and basic happy/sad expressions.

Failure to either assign landmarks onto the base mesh, or failure to deform landmarks appropriately can occur for several reasons. For more information, see [common issues](#common-issues).

### Landmark projection

Validation uses the head cage to project landmarks onto the head mesh. This helps Roblox establish where the eyes and mouth are and helps guide the facial animation test.

_Cage mesh: Specific vertices of the cage mark eyes and mouth._

_Roblox validation projects these points onto the head mesh._

_ Head mesh: All landmarks projected from cage mesh to head mesh._

> **Success:** Once validation verifies that projection is successful and all landmarks established onto the head mesh, it can move onto testing facial animations.
### Test face animations

Now that the validation system knows where to check for the eyes and mouth, the validation checks for facial animations to ensure that the following basic actions are possible:

- Left and right eyes can close
- Mouth can open
- Basic happy and sad expressions
  - For a full list of basic action units and poses, see [FACS animations](/docs/en-us/avatar/dynamic-heads/specifications.md#facs-animation).

The validation looks for the **relative change in the landmarks**. For example, when testing for right eye closing (FACS pose: `RightEyeClosed`), validation checks if the landmarks move from their original neutral state accordingly.

_> **Success:** Face mesh with all projected landmarks applied from cage._

_> **Success:** Validation verifies that the right eye can close based off of displacement of landmarks._

## Common issues

Validation checks for several aspects of your head asset. If you are receiving an error related to dynamic head animation, use the following table for potential culprits:

| Issue | Potential fixes |
| --- | --- |
| The validation tool is **unable to successfully apply landmarks**.<br><br>See [Unable to project landmarks](#unable-to-project-landmarks). | - Verify that the **cage landmark vertices are positioned directly over the corresponding areas of the face**.<br><br>- Verify that the **cage is not intersecting with the head mesh**. Landmark projection expects the cage to be over the head mesh.<br><br>- **Check for any gaps, holes, or difficult surfaces** of the face where landmarks can fail to project. |
| The validation tool is able to apply landmarks, but **can not detect animation**.<br><br>See [Animations not displacing landmarks](#animations-not-displacing-landmarks). | - Verify that **landmarks are on the areas of the eyes and mouth that move during animation**.<br><br>- Verify that the **cage is not intersecting with the head mesh**. Landmark projection expects the cage to be over the head mesh.<br><br>- **If using separate meshes for eyeballs and mouthbags**, ensure that your landmarks are applied to the head mesh, not the eyeballs or mouthbag. This can be achieved by slightly widening the area where your cages project landmarks. |
| The validation tool doesn't detect [FACS animations](#animation-data-missing). | - Your head doesn't include FACS animation. Verify that your head includes FACS poses and mapping. |

### Unable to project landmarks

If validation is unable to apply the projection correctly onto the surface of the head, the validation fails. This often occurs if your **cage extends beyond your head mesh**, or if your head mesh has a **hole or gap** that prevents the application of the landmark. See the following examples:

_> **Error:** Cage **extends too far beyond the mesh** and the validation is unable to apply 3 landmarks to the base mesh._

_> **Error:** Base mesh has a **hollow gap** in the design, preventing validation from applying 3 landmarks to denote the eye area._

> **Success:** In both cases, adjusting the cage to allow the proper projection of landmarks to the base mesh would resolve this issue.
### Animations not displacing landmarks

In the case where landmarks are correctly applied to the base mesh and the base mesh includes FACS data, it's possible that the facial animations do not displace the landmarks enough to pass validation. See the following example:

_> **Warning:** Landmarks successfully established on base mesh, but are not near the expected regions._

_> **Error:** When testing animations, validation doesn't detect the expected change to the landmark regions._

> **Success:** In the example case, adjusting the cage to allow the proper projection of landmarks at the appropriate areas would resolve this issue.

There may also be cases where the landmarks are correct, but the animation itself does not alter the projected landscapes enough to pass validation. In these cases, fixing the animation and/or optimizing the cage could help the validation properly identify the facial animation.

### Animation data missing

Heads require [17 specific FACS poses](/docs/en-us/avatar/dynamic-heads/specifications.md#facs-animation) that are used to test the 5 basic actions. Regardless of landmarks or other FACS animations, validation immediately fails if the minimum 17 poses were not detected.

For information on how to pose and map dynamic heads, see [Creating basic heads](/docs/en-us/art/characters/facial-animation/create-basic-heads.md).

## Working with non-humanoids

Some character models, typically non-humanoids, have unnatural or missing eyes and mouths. The most common case of this is the classic blocky features.

In this case, the cage still applies the expected landscapes to the head surface, and Roblox validates if facial animations correctly displace the facial animations.

_The cage for a blocky character applies landmarks to the surface of the head._

_Ensure that the landmarks are applied in areas where animation can effectively move the landmarks._

_Validation checks the displacement of the landmarks to verify facial animation. Make sure that your [FACS animations](/docs/en-us/avatar/dynamic-heads/specifications.md#facs-animation) properly affect the region where landmarks are applied._

In cases where eyes and mouths might be missing, the validation still projects landmarks and expects facial animation in those areas.

_Although this character doesn't have eyes or mouth, the cage still attempts to project landmarks for those features._

_In this example, the cage landmarks apply to the surface of this eye-less character head._

_Validation checks the displacement of the landmarks to verify facial animation. Make sure that your [FACS animations](/docs/en-us/avatar/dynamic-heads/specifications.md#facs-animation) properly affect the regions where the landmarks are applied._