Skip to main content

Troubleshooting

Common issues and solutions for ElysGenAIPlugin.

Enable Logging​

Enable detailed logging for debugging:

// DefaultEngine.ini
[Core.Log]
LogElysGenAI=Verbose
LogElysAudio=Verbose
LogElysSTT=Verbose
LogElysLLM=Verbose

Check Output Log window for detailed information.

Installation Issues​

Plugin Not Appearing in Editor​

Symptom: ElysGenAI not listed in Plugins window

Solutions:

  1. Verify .uplugin file exists at: YourProject/Plugins/ElysGenAIPlugin/ElysGenAIPlugin.uplugin
  2. Check .uplugin syntax (valid JSON)
  3. Regenerate project files: Right-click .uproject → Generate Visual Studio Project Files
  4. Delete Intermediate, Binaries, Saved folders and regenerate
  5. Check Output Log for plugin loading errors

Compilation Errors​

Error: unresolved external symbol UDeveloperSettings

Solution: Add to game .Build.cs:

PublicDependencyModuleNames.AddRange(new string[] {
    "DeveloperSettings"
});

Error: Module 'ElysGenAICore' not found

Solution:

  1. Check plugin is enabled in .uproject
  2. Verify all module .Build.cs files exist
  3. Clean and rebuild project

Audio Capture Issues​

No Audio Captured​

Symptoms:

  • IsCapturing() returns false
  • No audio data in consumers
  • Silence in recordings

Solutions:

  1. Check Microphone Permissions

    • Windows: Settings → Privacy → Microphone → Allow desktop apps
    • Mac: System Preferences → Security & Privacy → Microphone

  2. Verify Default Audio Device

    • Windows: Sound Settings → Input → Select correct microphone
    • Mac: System Preferences → Sound → Input

  3. Check Subsystem Initialization

    UERP_AudioCaptureSubsystem* AudioSubsystem = 
        GetGameInstance()->GetSubsystem<UERP_AudioCaptureSubsystem>();

    if (!AudioSubsystem)
    {
        UE_LOG(LogTemp, Error, TEXT("Audio subsystem not found!"));
    }

    if (!AudioSubsystem->IsCapturing())
    {
        AudioSubsystem->StartCapture();
    }

  4. Check Output Log:

    LogElysAudio: Audio capture failed to initialize
    LogElysAudio: No audio input device available

Audio on Dedicated Server​

Error: STT Component on dedicated server - audio capture disabled

Explanation: This is EXPECTED behavior. Audio should never be captured on dedicated servers.

Solution: Ensure STT components only initialize on clients:

if (GetNetMode() == NM_DedicatedServer)
{
    return;  // Don't initialize audio on server
}

STT Issues​

No Transcriptions​

Symptoms:

  • OnTranscriptionComplete never fires
  • Empty transcription results

Solutions:

  1. Check Listening State

    if (!STTComponent->IsListening())
    {
        STTComponent->StartListening();
    }

  2. Check Model Loaded

    // Output Log should show:
    LogElysSTT: Whisper model loaded: whisper-base.en.bin

  3. Verify Model Path

    • Check Project Settings → Elys GenAI → STT → Model Path
    • Default bundled path: ElysGenAIPlugin/Content/AI/Models/Whisper/whisper-base.en.bin

  4. Check Network Mode

    // STT disabled on dedicated servers
    if (GetNetMode() == NM_DedicatedServer)
    {
        UE_LOG(LogTemp, Warning, TEXT("STT on dedicated server!"));
    }

Low Confidence Scores​

Symptom: Transcriptions with confidence < 0.5

Solutions:

  1. Use Correct Language Model

    // English-only model for English speech
    STTComponent->SetLanguageCode(TEXT("en"));
    // Use whisper-base.en.bin (not whisper-base.bin)

  2. Improve Audio Quality

    • Speak closer to microphone
    • Reduce background noise
    • Use better microphone

  3. Enable VAD

    STTComponent->SetEnableVAD(true);

  4. Increase Buffer Duration

    // Project Settings → Audio → Buffer Duration
    BufferDuration = 200ms;  // Default: 100ms

LLM Issues​

Model Not Loading​

Error: Failed to load LLM model

Solutions:

  1. Check Model Path

    // Project Settings → Elys GenAI → LLM → Model Path
    // Default: ElysGenAIPlugin/Content/AI/Models/Phi3/phi-3-mini-4k-instruct-q4.gguf

  2. Verify Model File Exists

    • Check file exists at specified path
    • Verify file size (~2.7GB for Phi-3-mini Q4)

  3. Check Available RAM

    // Phi-3-mini requires ~4GB RAM
    // Check system has enough free memory

  4. Check Output Log

    LogElysLLM: Loading model: phi-3-mini-4k-instruct-q4.gguf
    LogElysLLM: Model loaded successfully

Slow Generation​

Symptom: Generation takes > 5 seconds per response

Solutions:

  1. Optimize Thread Count

    // Project Settings → LLM → NumThreads
    NumThreads = 4;  // Match CPU core count

  2. Reduce Context Length

    LLMComponent->SetMaxTokens(128);  // Default: 256

  3. Clear History

    LLMComponent->ClearHistory();  // Reduce context size

  4. Lower Temperature

    LLMComponent->SetTemperature(0.3f);  // Faster, less creative

Out of Memory​

Error: Failed to allocate memory for model

Solutions:

  1. Use Smaller Model

    • Phi-3-mini Q4: ~2.7GB (recommended)
    • TinyLlama Q4: ~600MB (faster, lower quality)

  2. Reduce Context Length

    // Project Settings → LLM → Context Length
    ContextLength = 2048;  // Default: 4096

  3. Close Other Applications

    • Free up system RAM
    • Monitor with Task Manager / Activity Monitor

Performance Issues​

High CPU Usage​

Symptom: CPU usage > 80% during generation

Solutions:

  1. Reduce Thread Count

    // Project Settings → STT/LLM → NumThreads
    NumThreads = 2;  // Lower if CPU maxed out

  2. Optimize Generation Settings

    LLMComponent->SetMaxTokens(128);  // Lower token count
    LLMComponent->SetTemperature(0.5f);  // Faster sampling

  3. Use Smaller Models

    • STT: tiny/base instead of medium/large
    • LLM: TinyLlama instead of Phi-3

High Memory Usage​

Symptom: RAM usage > 8GB

Solutions:

  1. Check Model Sizes

    Whisper base.en: ~74MB
    Phi-3-mini Q4: ~2.7GB
    Total: ~3GB for both

  2. Reduce Context Length

    LLMComponent->SetMaxHistoryMessages(10);  // Default: 20

  3. Unload Models When Not Needed

    Subsystem->GetBackend()->UnloadModel();

Blueprint Issues​

Events Not Firing​

Symptom: OnTranscriptionComplete or OnGenerationComplete never fires

Solutions:

  1. Check Event Binding

    • In Blueprint, ensure event is bound BEFORE calling StartListening() or SendMessage()

  2. Verify Component Initialized

    if (!STTComponent)
    {
        UE_LOG(LogTemp, Error, TEXT("STT Component is null!"));
    }

  3. Check Output Log

    LogElysSTT: Transcription complete: "hello" (0.85)
    LogElysSTT: Broadcasting OnTranscriptionComplete

Component Not Found​

Error: FindComponentByClass returned null

Solution:

  • Ensure component is added in Blueprint or C++
  • Check component is not disabled
  • Verify component class name is correct

Common Pitfalls​

Audio Replication Attempt​

Error: Trying to replicate audio data over network

Solution: Never replicate raw audio. Only replicate transcribed text:

// DON'T
UFUNCTION(Server, Reliable)
void ServerSendAudio(const TArray<float>& Audio);  // ❌ TOO LARGE

// DO
UFUNCTION(Server, Reliable)
void ServerSendText(const FString& Text);  // ✅ EFFICIENT

Model Path Packaged Game​

Error: Model not found in packaged game

Solution:

  1. Ensure models are in Content/ folder (packaged automatically)
  2. Use relative paths: ElysGenAIPlugin/Content/AI/Models/...
  3. Check pak file includes models

Multiple STT Components​

Issue: Multiple STT components on same actor

Solution: Only one STT component per actor. Use single component with consumer pattern for multiple outputs.

Getting Help​

Still having issues?

  1. Check Output Log with verbose logging enabled
  2. Search GitHub Issues: github.com/RogueParadigm/ElysGenAIPlugin/issues
  3. Create New Issue with:
    • Unreal Engine version
    • Plugin version
    • Output Log (relevant sections)
    • Steps to reproduce
  4. Join Discord: discord.gg/rogueparadigm
  5. Email Support: support@rogueparadigm.com

Next Steps​