Resources
Troubleshooting

Troubleshooting

Solutions to common issues with Avatarium.

Avatar Not Loading

Symptoms

  • Blank space where avatar should appear
  • Loading spinner that never completes
  • Console errors about WebGL

Solutions

1. Check browser compatibility

Ensure you're using a supported browser with WebGL enabled:

// Check WebGL support
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl');
console.log('WebGL supported:', !!gl);

2. Verify API key

Ensure your API key is valid and has not expired:

curl https://api.avatarium.ai/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Check container sizing

The avatar container must have explicit dimensions:

// ❌ Won't work - no height
<div>
  <Avatar model="scarlett" />
</div>
 
// ✅ Works - explicit dimensions
<div style={{ width: '400px', height: '600px' }}>
  <Avatar model="scarlett" />
</div>

No Audio / Voice Not Playing

Symptoms

  • Avatar appears but doesn't speak
  • Greeting message doesn't play
  • No sound during conversation

Solutions

1. Check browser autoplay policies

Modern browsers block autoplay. Audio requires user interaction:

function App() {
  const [started, setStarted] = useState(false);
 
  if (!started) {
    return (
      <button onClick={() => setStarted(true)}>
        Start Chat
      </button>
    );
  }
 
  return <Avatar model="scarlett" />;
}

2. Verify TTS configuration

Ensure your TTS provider is properly configured:

<AvatariumProvider
  ttsProvider={{
    type: 'elevenlabs',
    apiKey: 'your-key', // Is this valid?
    voiceId: 'rachel'   // Is this a valid voice ID?
  }}
>

3. Check browser audio permissions

Ensure the site has audio playback permission in browser settings.

Microphone Not Working

Symptoms

  • Voice input button doesn't respond
  • "Microphone access denied" error
  • Audio input not detected

Solutions

1. Grant microphone permission

When prompted, click "Allow" for microphone access.

2. Check HTTPS

Microphone access requires HTTPS. It won't work on http:// (except localhost).

3. Verify no other app is using microphone

Close other apps that might be using the microphone (Zoom, Teams, etc.).

High Latency / Slow Responses

Symptoms

  • Long delays between user message and avatar response
  • Conversations feel unnatural
  • Timeouts

Solutions

1. Check your AI provider

Some models are slower than others:

  • GPT-3.5-turbo: Fastest
  • GPT-4o: Fast
  • GPT-4: Slower
  • Claude Opus: Slowest

2. Reduce personality prompt length

Shorter prompts process faster. Keep under 1,000 characters if possible.

3. Check network connection

Run a speed test. Avatarium requires stable internet for real-time streaming.

Embed Not Working

Symptoms

  • Iframe shows blank or error
  • "Refused to connect" error
  • Widget doesn't appear

Solutions

1. Check embed permissions

Ensure embedding is enabled for your avatar in Dashboard > Avatar > Settings.

2. Verify Content Security Policy

Your site's CSP must allow iframes from avatarium.ai:

<meta http-equiv="Content-Security-Policy"
  content="frame-src https://avatarium.ai">

3. Use HTTPS

Embeds only work on HTTPS sites (except localhost).

Lip Sync Issues

Symptoms

  • Lips don't move when speaking
  • Lip movement doesn't match audio
  • Expressions not working

Solutions

1. Check model compatibility

Custom models need ARKit blend shapes. Verify your model includes:

  • viseme_sil, viseme_aa, viseme_E, etc.

2. Use Ready Player Me with correct parameters

Add morph targets to your URL:

?morphTargets=ARKit,Oculus+Visemes,mouthOpen,mouthSmile

3. Test with built-in avatars

Try a built-in avatar (like scarlett) to verify the issue is model-specific.

Still Having Issues?

If none of these solutions work:

  1. Search the Community Discord (opens in a new tab)
  2. Contact support@avatarium.ai with:
    • Your account email
    • Browser and OS version
    • Console error messages (if any)
    • Steps to reproduce the issue
FAQ