Troubleshooting

Find fixes for installation, API key, audio, lip sync, and connection problems in the Convai Unreal Engine plugin, plus log export and diagnostic guidance.

This section covers problems that occur at the plugin level: installation, authentication, session startup, microphone capture, general lip sync setup, and diagnostics. If the Convai Unreal Engine plugin connects successfully but one feature behaves incorrectly, start with that feature's troubleshooting page.

Not sure where to start? Open the Unreal Editor Output Log (Window > Output Log) and look for the first Convai error or warning. Use the log category as the route: LogConvai or LogConvaiEditor → Installation and plugin issues; ConvaiConnectionManagerLog, ConvaiSubsystemLog, or ConvaiChatbotComponentLog → Connection and API key issues; ConvaiAudioLog, ConvaiAudioStreamerLog, or ConvaiPlayerLog → Audio and microphone issues; ConvaiFaceSyncLog → Lip sync and animation issues. If no Convai category appears, start with Installation and plugin issues.

Troubleshooting categories

Installation and plugin issues Plugin not found, module load failures, Blueprint-only project limitations, and Android packaging errors.

Connection and API key issues Authentication failures, missing API key, session timeout errors, and firewall configuration.

Audio and microphone issues No audio input, wrong capture device, Android permission failures, and audio playback errors.

Lip sync and animation issues No mouth movement, wrong blendshape curves, frame starvation, and packaged build animation failures.

Diagnostics and log export Log categories, verbosity control, configuration defaults, Blueprint diagnostic nodes, and log file export for support.

Inspect a character with the Convai Debug Overlay See what a character actually knows at runtime: its context states, facts, surroundings sentences, and action queue.

Convai Debug Overlay reference Every panel, glyph, and key the overlay responds to, and the settings that control it.

Feature-specific troubleshooting

Problems that occur after the plugin connects successfully — where a specific feature behaves incorrectly — are documented inside each feature's own section.

Feature	Troubleshooting page
Character actions	Troubleshoot character actions
Dynamic context	Troubleshoot dynamic context
Emotion	Troubleshoot emotion
Long-term memory	Troubleshoot long-term memory
Narrative design	Troubleshoot narrative design
Scene metadata	Troubleshoot scene metadata
Vision	Troubleshoot vision
Gaze attention	Troubleshoot gaze attention
Lip sync	Troubleshoot lip sync

Next steps

When a problem is hard to diagnose from a single error message, enable verbose logging for the relevant category and inspect the Output Log. The diagnostics page also explains where Unreal writes logs and how to create a shareable support package from the Convai editor window.

Diagnostics and log export