AvatarController.onError callback as AvatarError.
- Web
- iOS
- Android
- Flutter
controller.onError = (error: AvatarError) => {
console.error('Error:', error.code, error.message)
}
controller.onError = { error in
print("Error: \(error)")
}
controller?.onError = { error ->
Log.e("Avatar", "Error: ${error.message}")
}
controller.onError = (error) {
debugPrint('Error: ${error.name}');
};
Web — ErrorCode
| Code | Description | Recovery |
|---|---|---|
appIDUnrecognized | App ID not recognized. | Verify your app ID in the dashboard. |
sessionTokenInvalid | Session token is invalid or appId mismatch. | Verify token generation on your server. |
sessionTokenExpired | Session token has expired. | Request a new token from your server. |
insufficientBalance | Account balance is insufficient. | Top up your account in the dashboard. |
sessionTimeout | Session timed out. | Reconnect by calling start() again. |
concurrentLimitExceeded | Concurrent connection limit exceeded. | Close other active sessions before starting a new one. |
avatarIDUnrecognized | Avatar ID not found. | Check the avatar ID exists and is published. |
failedToFetchAvatarMetadata | Failed to fetch avatar metadata. | Check network connectivity and retry. |
invalidAvatarMetadata | Avatar metadata is invalid. | Verify the avatar asset version or contact Spatius support. |
failedToDownloadAvatarAssets | Failed to download avatar assets. | Check network connectivity and retry. |
websocketError | WebSocket handshake or network error. | Check network connectivity, region, and proxy settings. |
websocketClosedAbnormally | WebSocket closed with code 1006. | Reconnect and inspect network stability. |
websocketClosedUnexpected | WebSocket closed with an unexpected close code. | Check the close reason and server logs. |
connectionInProgress | A connection is already being established. | Wait for the current start() call to complete. |
networkLayerNotAvailable | Direct Mode network layer is not available. | Ensure the SDK is initialized with DrivingServiceMode.direct before calling Direct Mode methods. |
playbackStartFailed | Failed to start playback. | Make sure initializeAudioContext() was called inside a user gesture. |
playbackInitFailed | Playback initialization failed. | Retry initialization from a user gesture and inspect browser audio permissions. |
audioOnlyInitFailed | Audio-only fallback initialization failed. | Retry or prompt the user to refresh the page. |
noAudio | No audio data is available for playback. | Check that your audio chunks are non-empty. |
audioContextNotInitialized | AudioContext has not been initialized. | Call initializeAudioContext() inside a user gesture before sending audio. |
animationPlayerNotInitialized | Animation player has not been initialized. | Reload the avatar and recreate the AvatarView. |
serverError | Server-side error. | Check the error message for details. |
iOS — AvatarError
| Error | Description | Recovery |
|---|---|---|
appIDUnrecognized | App ID not recognized. | Verify your app ID in the dashboard. |
sessionTokenInvalid | Session token is invalid or appId mismatch. | Verify token generation on your server. |
sessionTokenExpired | Session token has expired. | Request a new token from your server. |
insufficientBalance | Account balance is insufficient. | Top up your account in the dashboard. |
sessionTimeout | Session timed out. | Reconnect by calling start() again. |
concurrentLimitExceeded | Concurrent connection limit exceeded. | Close other active sessions before starting a new one. |
avatarIDUnrecognized | Avatar ID not found. | Check the avatar ID exists and is published. |
avatarAssetMissing | Avatar asset is missing locally. | Re-download with AvatarManager.load(). |
failedToFetchAvatarMetadata | Failed to fetch avatar metadata. | Check network connectivity and retry. |
invalidAvatarMetadata | Avatar metadata is invalid. | Verify the avatar asset version or contact Spatius support. |
incompatibleAvatarAsset | Avatar asset is incompatible with the SDK. | Upgrade the SDK or regenerate the avatar assets. |
failedToDownloadAvatarAssets | Failed to download avatar assets. | Check network connectivity and retry. |
invalidAnimationData | Motion data payload is invalid. | Verify your Backend Mode or RTC data path. |
serverError(code, message) | Server-side error. | Check the error message for details. |
Android — AvatarError
| Error | Description | Recovery |
|---|---|---|
AppIDUnrecognized | App ID not recognized. | Verify your app ID in the dashboard. |
SessionTokenInvalid | Session token is invalid or appId mismatch. | Verify token generation on your server. |
SessionTokenExpired | Session token has expired. | Request a new token from your server. |
InsufficientBalance | Account balance is insufficient. | Top up your account in the dashboard. |
SessionTimeout | Session timed out. | Reconnect by calling start() again. |
ConcurrentLimitExceeded | Concurrent connection limit exceeded. | Close other active sessions before starting a new one. |
AvatarIDUnrecognized | Avatar ID not found. | Check the avatar ID exists and is published. |
FailedToFetchAvatarMetadata | Failed to fetch avatar metadata. | Check network connectivity and retry. |
InvalidAvatarMetadata | Avatar metadata is invalid. | Verify the avatar asset version or contact Spatius support. |
IncompatibleAvatarAsset | Avatar asset is incompatible with the SDK. | Upgrade the SDK or regenerate the avatar assets. |
FailedToDownloadAvatarAssets | Failed to download avatar assets. | Check network connectivity and retry. |
InvalidAnimationData | Motion data payload is invalid. | Verify your Backend Mode or RTC data path. |
ServerError(message, code) | Server-side error. | Check the error message for details. |
Flutter — AvatarError
Flutter surfacesAvatarError through AvatarController.onError. Error names match the client SDK categories above; log error.name and the current lifecycle phase for recovery.
Recommended Handling Flow
- Log the error code and current lifecycle phase.
- Retry transient network/download failures with backoff.
- Refresh session token for auth-related errors.
- Surface configuration errors to developers/operators.