Links
Comment on page

Troubleshooting Guide

Common Issues (FAQ)

Q. I cannot see the Convai menu.

A. Please check if there are any errors in the console. Unity needs to be able to compile all the scripts to be able to display any custom editor menu options. Resolving all the console errors will fix this issue.

Q. There are a lot of errors on my console.

A. Primarily, three issues cause errors in the console that can stem from the Convai Unity Plugin. You can use the links below to fix them quickly.

Q. I am talking to the character, but I cannot see the user transcript and the character does not seem to be coherently responding to what I am saying.

A. This may indicate issues with the microphone. Please ensure that the microphone is connected correctly. You also need to ensure that the applications have permission to access the menu.

Q. My character seems to be saying something and I can see the transcript but I cannot hear the character.

A. If we are using OVR with our models, we might need to enable audio loopback so that the audio can play.

Q. The animations for my characters are looking very weird.

A. The animation avatar that we are using might be incompatible with the character mesh. Fixing that can solve the issue.

Q: The lipsync is very faint or not visible.

A: The animations that we are using may be modifying facial animations. Editing the animations to remove facial animations should fix any issues related to lipsync.
A: The script also needs the avatar to not be mapped to the jaw bone to be manipulate the jaw bones itself.
Q: I'm facing security permission issues using the grpc_csharp_ext.bundle DLL inside the Unity Editor on MacOS
A: macOS's strict security measures can block certain external unsigned DLLs. To address this, you can manually allow the DLL in "Security & Privacy" settings, modify Gatekeeper's settings through Terminal, ensure correct file permissions for the DLL, check its settings in Unity, and update the Mac Configuration in Unity's Player Settings
Q: I'm not able to talk to my character after building my Unity project for macOS (Intel64+Apple Silicon builds), especially on Intel Macs
A: The issue is rooted in the grpc_csharp_ext.bundle used in Unity for networking. This DLL has separate versions optimized for Intel and Apple Silicon architectures. When trying to create a Universal build that serves both, compatibility problems arise, especially on Intel Macs. Presently, the best solution is to use Standalone build settings specific to each architecture.

Error Index

Follow this Table to navigate to our most common errors.
Name
Sample Error
Reason for Error
Text
Enabled Assembly Validation
Assembly 'Assets/Convai/Plugins/Grpc.Core.Api/lib/net45/Grpc.Core.Api.dll' will not be loaded due to errors:
Grpc.Core.Api references strong named System.Memory Assembly references: 4.0.1.1 Found in project: 4.0.1.2.
Unity, by default, checks for exact version numbers for the included assemblies. For our plugin, this is not necessary, since we use the latest libraries.
Missing NewtonSoft Json
Assets\Convai\Plugins\GLTFUtility\Scripts\Spec\GLTFPrimitive.cs(8,4): error CS0246: The type or namespace name 'JsonPropertyAttribute' could not be found (are you missing a using directive or an assembly reference?)
Our plugin needs Newtonsoft Json as a dependency. It is often present as part of Unity but occasionally, it can be missing.
Missing Animation Rigging
Assets\Convai\Scripts\Utils\HeadMovement.cs (2,30): error CS0234: The type or namespace name 'Rigging' does not exist in the namespace 'UnityEngine.Animations' (are you missing an assembly reference?)
We use the Animation Rigging package for Eye and Neck tracking. If Unity does not automatically add it, we need to add it manually from the package manager.
Microphone Permission Issues
The microphone icon lights up but there is no user transcript in the chat UI. The character seemingly not replying to what the user is saying.
The plugin requires microphone access which is sometimes not enabled by default.
OVR Lip-sync Audio Loopback not Enabled
There is not sound coming from the character but transcripts are visible.
Default Animations Incompatibility
The default animations that ship with the plugin seems broken. The hands seem to intersect with the body.
The animation avatar is incompatible with the character mesh.
Animations have Facial Blendshapes
The Lip-sync from characters are either not visible or are very faint.
Some types of animations control facial blendshapes. These animations prevent the lip-sync scripts to properly edit the facial blendshapes.
Jaw Bone in Avatar is not Free
The Lip-sync from characters are either not visible or are very faint.
The animation avatar for the character may be using the Jaw Bone. If we set the mapping free to none, the script will be able to manipulate the jaw bone freely.
Mac Security Permission Issue
Security Permission Issues with grpc_csharp_ext.bundle DLL in Unity on MacOS.
MacOS's security protocols can prevent certain unsigned external DLLs, like grpc_csharp_ext.bundle, from functioning correctly in Unity.
Microphone Permission Issue with Universal Builds on Intel Macs in Unity
No Microphone access request pops up
Incompatibility between Intel and Apple Silicon versions of grpc_csharp_ext.bundle when attempting a Universal build.
For any other issues, please feel free to reach out to [email protected] or on our Discord Server.