Troubleshooting & Diagnostics

Step-by-step fixes for the most common Emotion system problems — from expressions that will not move to LipSync conflicts and production build gotchas.

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.

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.

First-Line Investigation

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

1

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.

2

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.

3

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.

4

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.

5

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.

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.

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.

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.

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.

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.

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.

Expressions Not Responding — Decision Tree

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.