> 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/convai-unreal-engine-plugin/troubleshooting.md).

# Troubleshooting

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.

{% hint style="info" %}
**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.
{% endhint %}

### Troubleshooting categories

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Installation and plugin issues</strong><br>Plugin not found, module load failures, Blueprint-only project limitations, and Android packaging errors.</td><td><a href="/pages/hAqxIeXv5sv60SseRsHZ">/pages/hAqxIeXv5sv60SseRsHZ</a></td></tr><tr><td><strong>Connection and API key issues</strong><br>Authentication failures, missing API key, session timeout errors, and firewall configuration.</td><td><a href="/pages/vjpN4AOUQxqogF37p0pC">/pages/vjpN4AOUQxqogF37p0pC</a></td></tr><tr><td><strong>Audio and microphone issues</strong><br>No audio input, wrong capture device, Android permission failures, and audio playback errors.</td><td><a href="/pages/dLpMCOKrWYMkRx1BXob8">/pages/dLpMCOKrWYMkRx1BXob8</a></td></tr><tr><td><strong>Lip sync and animation issues</strong><br>No mouth movement, wrong blendshape curves, frame starvation, and packaged build animation failures.</td><td><a href="/pages/I0ObYlUKKH4xrA1bmEGA">/pages/I0ObYlUKKH4xrA1bmEGA</a></td></tr><tr><td><strong>Diagnostics and log export</strong><br>Log categories, verbosity control, configuration defaults, Blueprint diagnostic nodes, and log file export for support.</td><td><a href="/pages/pZV8WWWMb3ZTg1Gyagbc">/pages/pZV8WWWMb3ZTg1Gyagbc</a></td></tr></tbody></table>

### 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](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/troubleshoot-character-actions.md) |
| Dynamic context   | [Troubleshoot dynamic context](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/dynamic-context/troubleshoot-dynamic-context.md)       |
| Emotion           | [Troubleshoot emotion](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/emotion/troubleshoot-emotion.md)                               |
| Long-term memory  | [Troubleshoot long-term memory](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/long-term-memory/troubleshoot-long-term-memory.md)    |
| Narrative design  | [Troubleshoot narrative design](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/narrative-design/troubleshoot-narrative-design.md)    |
| Scene metadata    | [Troubleshoot scene metadata](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md)          |
| Vision            | [Troubleshoot vision](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/vision/troubleshoot-vision.md)                                  |
| Gaze attention    | [Troubleshoot gaze attention](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.md)          |
| Lip sync          | [Troubleshoot lip sync](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/lip-sync/troubleshoot-lip-sync.md)                            |

### 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.

{% content-ref url="/pages/pZV8WWWMb3ZTg1Gyagbc" %}
[Diagnostics and log export](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/troubleshooting/diagnostics-and-log-export.md)
{% endcontent-ref %}


---

# 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/convai-unreal-engine-plugin/troubleshooting.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.