> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/emotion/troubleshooting-and-diagnostics.md).

# Troubleshooting & Diagnostics

## Diagnosing and Resolving Emotion Problems

Most Emotion problems fall into one of three categories: no visual output at all, scores updating but no face movement, or event and scripting callbacks not firing. This page starts with the built-in Inspector inspection surface, then walks through a structured first-line checklist, a quick-reference table, detailed per-issue sections, a console log reference, and a decision tree for the most common failure path.

## Inspecting Live State

`ConvaiEmotionController` exposes the full pipeline state in the Inspector during Play Mode without any additional tooling.

| What to watch                | Where to find it                                 | What it tells you                                                                                                                    |
| ---------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Current → Dominant Label** | `ConvaiEmotionController` Inspector in Play Mode | Which canonical emotion is currently dominant. `"neutral"` means no active signal.                                                   |
| **Current → Dominant Score** | `ConvaiEmotionController` Inspector in Play Mode | Smoothed intensity \[0–1] of the dominant emotion. A value above 0 confirms the pipeline is receiving and processing server signals. |
| **Lock Emotion** checkbox    | `ConvaiEmotionController` Inspector (any mode)   | When ticked, server signals are ignored. The character holds the locked expression.                                                  |

To preview blendshape slot mappings without entering Play Mode, enable **Lock Emotion**, set **Locked Emotion Label** to a canonical label, and set **Locked Intensity** to `1.0`. Because `ConvaiEmotionController` is `[ExecuteAlways]`, blendshapes update immediately in the Scene view — no Play Mode required.

{% hint style="danger" %}
**Lock Emotion** is a serialised field. Its value is saved with the scene or prefab. Always disable it before building for production — a serialised `true` silently disables all live emotion response in the shipped build.
{% endhint %}

## First-Line Investigation

Work through this checklist in order when emotion is not behaving as expected. Most issues resolve at step 1 or 2.

{% stepper %}
{% step %}
**Check the Profile field**

Select your NPC's root GameObject. On the `ConvaiEmotionController` component, confirm the **Profile** field is not empty.

* **Empty** → Drag in a `ConvaiEmotionProfile` asset. For a quick test, use the bundled `ConvaiSamplesShared_EmotionProfile` from `Packages / Convai SDK for Unity / SamplesShared / Resources / Embodiment / Modules / Emotion`. The pipeline will not run without a profile.
* **Assigned** → Continue to the next step.
  {% endstep %}

{% step %}
**Watch DominantScore in Play Mode**

Press **Play**, speak to the character, and observe **Current → Dominant Score** on the `ConvaiEmotionController` Inspector.

* **Score rises above 0** → The pipeline is receiving server signals. The problem is in the output bindings. Skip to step 4.
* **Score stays at 0** → The controller is not receiving emotion signals. Continue to step 3.
  {% endstep %}

{% step %}
**Check Lock Emotion and component placement**

Two quick causes prevent signals from reaching the accumulator:

1. **Lock Emotion is ticked** → Disable it. The controller discards all server events while locked.
2. **Component is on the wrong GameObject** → `ConvaiEmotionController` must be on the **same root GameObject** as the Embodiment component. On a child object or a different NPC, it will not receive emotion events from the correct character session.

If neither applies, verify the character is actively connected — it should respond to speech in the Console before emotion signals can arrive.
{% endstep %}

{% step %}
**Check output slot population**

Open the `ConvaiEmotionProfile` asset. If both the **Blendshape Binding** and **Animator Binding** lists are empty, the pipeline runs internally but writes nowhere — `DominantScore` updates, but no face movement occurs.

Add at least one `EmotionSlotBinding` with a valid `emotionLabel` and a blendshape name or Animator parameter that exists on your character. See Output Bindings.
{% endstep %}

{% step %}
**Verify blendshape names and slot labels**

If `DominantScore` updates but the face still does not move:

1. Select your character's mesh GameObject → Inspector → **Skinned Mesh Renderer** → expand **BlendShapes**.
2. Copy the exact blendshape name into your slot's **Blendshape Names** field. Names are **case-sensitive**.
3. Confirm the slot's **Emotion Label** field uses the **canonical** taxonomy label (e.g. `"joy"`, not the server alias `"happy"`). The binding matches against the canonical label — an alias will never resolve.
   {% endstep %}
   {% endstepper %}

## Common Issues

| Symptom                                                           | Likely cause                                                      | Fix                                                                                             |
| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Face does not move at all; DominantScore stays at 0**           | No profile assigned                                               | Assign a `ConvaiEmotionProfile` to the **Profile** field                                        |
| **Face does not move at all; DominantScore stays at 0**           | Lock Emotion is enabled                                           | Disable **Lock Emotion** on `ConvaiEmotionController`                                           |
| **Face does not move at all; DominantScore stays at 0**           | Component on wrong GameObject                                     | Move `ConvaiEmotionController` to the NPC's root GameObject, alongside the Embodiment component |
| **DominantScore updates but face unchanged**                      | Output slots are empty                                            | Add at least one slot with a valid emotion label and blendshape name to the profile             |
| **DominantScore updates but face unchanged**                      | Blendshape name mismatch                                          | Copy the exact name from **Skinned Mesh Renderer → BlendShapes**; names are case-sensitive      |
| **DominantScore updates but face unchanged**                      | Slot `emotionLabel` uses server alias                             | Use the canonical label (`"joy"`, not `"happy"`) in the slot's **Emotion Label** field          |
| **DominantScore updates but face unchanged**                      | `weightMultiplier` or `fullBlendshapeWeight` is 0                 | Set both to non-zero values in the slot                                                         |
| **Specific emotion never appears; character stays neutral**       | Server label not in taxonomy; silent fallback to neutral          | Add the server label as an alias to the nearest canonical entry in a custom taxonomy            |
| **LipSync stops working during speech**                           | Non-mouth blendshapes marked `isMouthShape = true`                | Set `isMouthShape = false` for brow, eye, cheek, and upper-face shapes                          |
| **Character holds one expression throughout the entire session**  | `lockEmotion` serialised as `true` in scene or prefab             | Disable **Lock Emotion**; save the scene (**Ctrl+S** / **Cmd+S**)                               |
| **No emotion response in production build**                       | `lockEmotion` left enabled before building                        | Disable **Lock Emotion** before building; verify per-prefab-instance in the Inspector           |
| **Profile changes revert after reopening the project**            | Editing the bundled read-only package asset                       | Duplicate the asset (**Ctrl+D** / **Cmd+D**), move the copy to `Assets/`, assign the copy       |
| **`OnEmotionChanged` on `ConvaiCharacterEventRelay` never fires** | Character reference not resolved                                  | Enable **Auto Resolve Character**, or assign `ConvaiCharacter` in the **Character** field       |
| **`[EmotionTaxonomyAsset]` warning in Console**                   | Custom taxonomy has no neutral entry, or multiple neutral entries | Set `IsNeutral = true` on exactly one taxonomy entry                                            |

## Unknown Server Labels — Silent Neutral Fallback

**Symptom:** An emotion the server sends never appears on the character. The face returns to neutral as if no signal arrived.

**Cause:** When the server sends a label that does not match any canonical label or alias in the active taxonomy, `TryResolve` returns false and the controller silently uses the neutral descriptor. Unlike a name mismatch in a blendshape slot, this failure **produces no console warning** — the pipeline continues normally, writing neutral scores every frame.

**How to detect it:**

1. In Play Mode, expand **Current → All Scores** on the `ConvaiEmotionController` Inspector. If an emotion you expect to see has a score of exactly 0.0 while the conversation clearly calls for it, the server label is likely not resolving.
2. Enable `lockEmotion` in the Inspector, set **Locked Emotion Label** to the canonical label you expect (e.g. `"anticipation"`), and confirm the blendshape slot activates. If it does, the output binding is correct — the signal simply never arrives from the server under that label.

**Fix:** Open your custom taxonomy asset (or create one if using the built-in default), and add the server label as an alias to the nearest semantic match. For example, if the server sends `"excited"` and it should map to the visual slot for `"anticipation"`, add `"excited"` to the **Aliases** list of the `anticipation` entry. See Emotion Taxonomy for how to create and assign a custom taxonomy.

## Blendshape Names Do Not Match

**Symptom:** `Current.DominantScore` updates correctly in Play Mode, but the character's face does not visually change.

**Cause:** The blendshape name in the `EmotionSlotBinding` does not exactly match the name on the `SkinnedMeshRenderer`.

**Fix:**

1. Select your character's mesh GameObject in the Hierarchy.
2. In the Inspector, scroll to the **Skinned Mesh Renderer** component.
3. Expand the **BlendShapes** section.
4. Copy the exact name from there into your slot's **Blendshape Names** field. Names are case-sensitive and must match exactly — including underscores, spaces, and capitalisation.

{% hint style="info" %}
If the character has multiple `SkinnedMeshRenderer` components (body, head, and teeth as separate meshes), the blendshape binding targets the mesh registered with the Embodiment compositor. Confirm which mesh your Embodiment component's rig binding references before copying names.
{% endhint %}

## LipSync Breaks When Emotion Is Active

**Symptom:** While the character is speaking, LipSync-driven mouth shapes stop working, or emotion shapes suppress phoneme shapes unexpectedly.

**Cause:** One or more blendshape slots have `isMouthShape = true` for shapes that deform brows, eyes, or cheeks rather than the lips or jaw. These shapes are routed through the mouth compositor layer — the same layer LipSync writes to during speech — which causes them to interfere with phoneme output.

**Fix:** Open the `ConvaiEmotionProfile` asset. In every **Blendshape Binding** slot, set `isMouthShape = true` **only** for shapes that deform the lips, jaw, or chin. Brow raises, eye squints, cheek puffs, and upper-face shapes should have `isMouthShape = false`.

## Expressions Frozen — Character Ignores Conversation

**Symptom:** The NPC holds a single expression throughout the session and never reacts to AI emotion signals.

**Cause:** `lockEmotion` is serialised as `true` in the scene or prefab — a common authoring artefact left over from Inspector preview.

**Fix:**

1. Select the NPC's root GameObject.
2. On `ConvaiEmotionController`, disable **Lock Emotion**.
3. Save the scene (**Ctrl+S** / **Cmd+S**).

If you have multiple NPC prefabs, check each one individually — the field persists per-prefab-instance unless explicitly overridden.

{% hint style="danger" %}
Always verify **Lock Emotion** is `false` before building for production. A serialised `true` value will silently disable all live emotion response in the shipped build with no runtime error.
{% endhint %}

## Profile Changes Are Not Saving

**Symptom:** You edit settings on the Emotion Profile asset, but the changes revert on reopening the project or returning to the Inspector.

**Cause:** You are editing the bundled read-only asset inside the package. Assets inside a Unity package cannot be modified.

**Fix:**

1. Select `ConvaiSamplesShared_EmotionProfile` in the Project window.
2. Duplicate it (**Ctrl+D** / **Cmd+D**).
3. Move the copy into your own `Assets/` folder.
4. On the `ConvaiEmotionController`, assign the copy instead of the original.

## ConvaiCharacterEventRelay OnEmotionChanged Does Not Fire

**Symptom:** You wired a Unity Event to **On Emotion Changed** on `ConvaiCharacterEventRelay`, but it never fires in Play Mode.

**Checklist:**

1. **Character reference:** Either **Auto Resolve Character** is enabled and a `ConvaiCharacter` is on the same GameObject, or you have manually assigned a `ConvaiCharacter` in the **Character** field. If neither is true, the relay logs a configuration warning and stays inactive.
2. **Component enabled:** Confirm the `ConvaiCharacterEventRelay` component is enabled (the checkbox in the Inspector header is ticked).
3. **Subscription timing:** The relay fires only after the Convai session is established. Subscribe in `OnEnable` and unsubscribe in `OnDisable` to catch all events from the moment the component activates. Events that arrive before the session is open may be missed.
4. **Session active:** `ConvaiCharacterEventRelay` fires when the character's `ConvaiCharacter` callbacks fire. If no signals arrive at all, confirm the character responds to speech normally before testing emotion callbacks.

## Emotion Scores Visible but No Output Binding Written

**Symptom:** `ConvaiEmotionController.Current.DominantScore` updates correctly in Play Mode, but neither blendshapes nor Animator parameters change.

**Checklist:**

1. Confirm the **Blendshape Binding** or **Animator Binding** list in the profile is not empty.
2. Confirm the `emotionLabel` in each slot matches a **canonical** taxonomy label — use `"joy"`, not the server alias `"happy"`.
3. For Animator bindings, confirm the parameter name exists as a **Float** in the Animator Controller and that the Animator component is on the same GameObject as `ConvaiEmotionController`.
4. Confirm `weightMultiplier` is greater than 0 and `fullBlendshapeWeight` is greater than 0 in each slot.

## Console Log Reference

The following messages appear in the Unity Console from the Emotion system. Use this table to understand what each message means and what to do next.

| Log message                                                                                                                                                                         | Component                 | Meaning                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[ConvaiEmotionController] Ignored an emotion event without a character id. Character-scoped emotion events must include a character id to avoid cross-character expression bleed.` | `ConvaiEmotionController` | An emotion event arrived with no character ID. Common in multi-NPC scenes where events are broadcast globally. Ensure each NPC has a unique **Character ID** set on its `ConvaiCharacter` component. Logged once per controller lifetime. |
| `[EmotionTaxonomyAsset] No entry marked neutral; synthesized 'neutral' fallback. Mark exactly one entry as the neutral baseline to suppress this warning.`                          | `EmotionTaxonomyAsset`    | A custom taxonomy asset has no entry with **IsNeutral** = true. The system synthesizes a fallback neutral so the pipeline runs. Set `IsNeutral = true` on exactly one entry to suppress the warning.                                      |
| `[EmotionTaxonomyAsset] No entry has IsNeutral set. A synthetic 'neutral' will be used at runtime; mark one entry as the neutral baseline.`                                         | `EmotionTaxonomyAsset`    | Same as above — fired in the Inspector (`OnValidate`) when you save the taxonomy asset in Edit Mode. Fix by marking one entry as the neutral baseline.                                                                                    |
| `[EmotionTaxonomyAsset] N entries are marked IsNeutral; only the first will be used. Mark exactly one neutral baseline.`                                                            | `EmotionTaxonomyAsset`    | Multiple taxonomy entries have **IsNeutral** = true. Only the first is used. Remove the `IsNeutral` flag from all but one entry.                                                                                                          |

{% hint style="info" %}
There is **no console warning** when the server sends an unrecognised emotion label. `TryResolve` silently falls back to the neutral descriptor. If an expected emotion never appears on the character, see Unknown Server Labels — Silent Neutral Fallback above.
{% endhint %}

## Expressions Not Responding — Decision Tree

```mermaid
flowchart TD
    A[Face not responding to emotion] --> B{Profile assigned?}
    B -- No --> C[Assign ConvaiEmotionProfile<br/>to the Profile field]
    B -- Yes --> D{DominantScore rises<br/>during conversation?}
    D -- No --> E{Lock Emotion enabled?}
    E -- Yes --> F[Disable Lock Emotion<br/>on ConvaiEmotionController]
    E -- No --> G{Controller on root<br/>GameObject?}
    G -- No --> H[Move controller to NPC root<br/>GameObject alongside Embodiment]
    G -- Yes --> I[Verify character session is<br/>active - test speech first]
    D -- Yes --> J{Output slots<br/>populated?}
    J -- No --> K[Add BlendshapeEmotionBinding<br/>slots with valid labels]
    J -- Yes --> L{Blendshape names<br/>exact match?}
    L -- No --> M[Copy exact names from<br/>SkinnedMeshRenderer BlendShapes]
    L -- Yes --> N{emotionLabel is<br/>canonical, not alias?}
    N -- No --> O[Use canonical label:<br/>&quot;joy&quot; not &quot;happy&quot;]
    N -- Yes --> P{weightMultiplier and<br/>fullBlendshapeWeight > 0?}
    P -- No --> Q[Set non-zero weight<br/>values in the slot]
    P -- Yes --> R[Check isMouthShape flags<br/>and LipSync compositor layer]
```

## Conclusion

Most Emotion problems reduce to one of four root causes: a missing profile, empty or misconfigured output slots, an accidentally serialised `lockEmotion`, or a blendshape name mismatch. Start by watching `Current.DominantScore` in Play Mode — if it updates, the pipeline is healthy and the issue is in the output bindings; if it stays at zero, work backward to the profile, lock state, and component placement. Use the Common Issues table for a fast lookup, the Console Log Reference to interpret warning messages, and the decision tree when the cause is not immediately clear.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/emotion/troubleshooting-and-diagnostics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.