Common Issues
Supported Audio Format
Supported Audio Format
Currently only support PCM 16-bit mono audio at multiple sample rates:
8000, 16000, 22050, 24000, 32000, 44100, 48000.See Audio Sample Rate for configuration details.
Avatar Playback Fallback Strategy
Avatar Playback Fallback Strategy
If the avatar animation drive data is abnormal after passing in audio, the fallback playback strategy will be triggered:
- Audio plays normally
- Animation plays idle breathing state / Animation stops
Session token expired or invalid
Session token expired or invalid
Session tokens have a limited lifetime. If you receive
sessionTokenExpired or sessionTokenInvalid, request a new token from your server and set it via AvatarSDK.sessionToken before reconnecting.Avatar assets fail to download
Avatar assets fail to download
Check your network connectivity and ensure the avatar ID is correct. If the issue persists, clear the local cache with
AvatarManager.clearAll() and retry. On mobile, verify that your app has network permissions.Platform-Specific
Web: WASM module fails to load
Web: WASM module fails to load
AvatarKit Web uses WebAssembly for rendering. Your build tool must be configured to handle
.wasm files:- Vite: Use the AvatarKit Vite plugin.
- Next.js: Use the AvatarKit Next.js wrapper component.
Web: WebGL not supported
Web: WebGL not supported
AvatarKit requires WebGL 2.0. Ensure the browser supports it and hardware acceleration is enabled. Most modern browsers support WebGL 2.0 by default.
iOS: Metal rendering requirements
iOS: Metal rendering requirements
AvatarKit iOS uses Metal for GPU rendering. Metal is available on all devices running iOS 16+. The simulator does not support Metal — test on a physical device.
Android: Vulkan rendering requirements
Android: Vulkan rendering requirements
AvatarKit Android uses Vulkan for GPU rendering. Ensure the target device supports Vulkan 1.1+ (API 24+). Most devices from 2018 onwards support Vulkan.
RTC: LiveKit version compatibility
RTC: LiveKit version compatibility
RTC Mode requires
livekit-client at exactly version 2.16.1. Other versions may cause connection or audio routing issues.Performance Issues
Avatar Rendering Resolution Support
Avatar Rendering Resolution Support
Our avatar models don’t use the concept of resolution.We can reconstruct 4K resolution 3D avatar models, but this depends on the model’s point count.Fewer points result in less detail restoration, but all models can be rendered to the corresponding resolution on the client side.Metrics such as PSNR and LPIPS are typically used to measure the quality of detail restoration.
Can the SDK dynamically switch between different models based on device performance?
Can the SDK dynamically switch between different models based on device performance?
Not currently supported. Developers need to implement their own strategy for switching between different models based on device performance.