Troubleshooting
Every error the SDK reports tells you what happened, where it failed, and what to do. This page lists them by area. The Message column is the text of the error's message; text in <angle brackets> is filled in at runtime.
Contact support with the source
Every error carries a source field: a short trace of the exact code path that failed. When you contact Vonage support, send the error's code and source, and the call or session ID if you have one.
For the error object itself and the full list of codes, see Errors. For how sessions reconnect, see Session lifecycle.
Session ended: onSessionError
onSessionError means the session has ended and will not recover on its own. A dropped connection does not fire it: the SDK fires onReconnecting and resumes the same session for up to 15 minutes.
| Reason (Android / iOS / Web) | Message | What to do |
|---|---|---|
TokenExpired / .tokenExpired / EXPIRED_TOKEN | The session ended because its JWT expired. Call refreshSession with a new token before it expires, or createSession with a new token now. | Get a new JWT from your backend, then call createSession. To avoid it, call refreshSession before the JWT's exp. |
TransportClosed / .transportClosed / TRANSPORT_CLOSED | The connection to Vonage was lost and could not be restored within 15 minutes, so Vonage has ended the session. Calls cannot be made or received until you call createSession again; do it when the device is back online. | Call createSession when the device is back online. The same JWT works if it has not expired. Also reported when Vonage ends the session for any other reason. |
PingTimeout / .pingTimeout / PING_TIMEOUT | — | Deprecated. Never reported. A missed heartbeat is a transient drop, reported through onReconnecting. |
createSession, refreshSession and deleteSession errors
| Code | Message | What to do |
|---|---|---|
session:error:websocket-transport-invalid | The session could not be created: this device could not connect to Vonage (WebSocket to <host>) after <n> attempts over <s> seconds. The device appears to be offline, or the network is blocking WebSocket connections. | Check the device's internet connection. On a corporate network, allow WebSocket traffic to the host in the message. The SDK retries for up to 60 seconds before reporting this. |
session:error:timeout | The session could not be created: the connection to Vonage opened, but Vonage did not confirm the session within 5 seconds. Try again; if it persists, contact Vonage support with this error's source. | Call createSession again. If it persists, contact support with the source. |
session:error:empty-token | You provided an empty token. Please provide a valid token. | Pass the JWT from your backend. |
session:error:invalid-token | You provided an invalid token. Please provide a valid token. | Check the JWT's signature, application_id and claims. |
session:error:expired-token | You provided an expired token. Please provide a valid token. | Get a new JWT from your backend. |
system:error:permission | Permission denied. Please provide a valid token. | Check the JWT's acl claim. |
session:error:invalid-session | The request failed due to an invalid session. Please establish a valid session and try again. | Call createSession again. If you passed a stored session ID, try without it. |
session:error:max-open-sessions-permitted | The maximum amount of open sessions has been established. Please delete them by logging out and try again. | Call deleteSession on logout, so old sessions do not accumulate. |
session:error:no-active-session | You do not have an active session. Please establish a valid session and try again. | There is no session: call createSession. Also reported by refreshSession after onSessionError. |
serverCall errors
| Code | Message | What to do |
|---|---|---|
media:error:create_media_error | Failed to start the call: this device could not open its microphone (<detail>). Check that the app has microphone permission and that no other app is using the microphone, then try again. | Check the microphone permission and that no other app is using the microphone. |
media:error:create_offer_error | Failed to start the call: this device could not set up the call's audio (<detail>). Try again; if it persists, contact Vonage support with this error's source. | Try again; if it persists, contact support with the source. |
voice:error:media_setup_failed | Failed to start the call: this device could not open an audio connection to Vonage after <n> attempts, so no call was placed. Something on the network is blocking real-time audio (WebRTC over UDP), typically a firewall, proxy or VPN. Try another network or allow WebRTC traffic. | Try another network, or allow WebRTC traffic on this one. |
voice:error:websocket_signaling_connection_lost | The call was placed, but this device lost its signalling connection to Vonage (WebSocket) while the call was being set up, and the connection did not come back within 30 seconds, so the SDK ended the call. Check the device's internet connection; connectionStatus reports when it is back. | Wait for connectionStatus to be Connected, then place the call again. |
voice:error:media_connection_lost | The call was placed, but this device's audio connection to Vonage dropped before the call connected and could not be restored, so the SDK ended the call. This is usually a network change or loss, for example switching between Wi-Fi and mobile data. | Place the call again once the network is stable. |
voice:error:call_not_confirmed | The call was placed and this device's connections to Vonage were working, but Vonage did not confirm that the call started. This is not a problem with the device or its network. Contact Vonage support with this error's source. | Contact support with the source. |
session:error:no-active-session | Failed to start the call: the session it was started on has ended. Start the call again. | createSession replaced the session, or it was deleted, while the call was being set up. Start the call again on the current session. With no session at all, the message is the generic one above: call createSession first. |
CS_ERROR codes | Failed to start the call: Vonage rejected the request (<detail>). | See Errors. If isRetriable is true, retry, after retryAfter if set. |
NETWORK_ERROR codes | Failed to start the call: the request did not reach Vonage. This device could not connect: it may be offline, or the network may be blocking the connection. | Check the device's internet connection, and on a corporate network that it allows traffic to Vonage, then try again. |
Busy, unknown number, rejected, carrier failure and no answer are not serverCall errors. The call was placed, and the outcome arrives as an onCallHangup reason.
answer errors
| Code | Message | What to do |
|---|---|---|
voice:error:call_already_ended | The call could not be answered because it had already ended: the caller hung up, or it was answered or rejected on another device. | Dismiss the incoming-call UI. |
voice:error:no_invite_found | No invite found | The SDK holds no invite with this ID: it was already handled or cancelled, or arrived on a session that has since been replaced. Dismiss the UI. |
voice:error:invalid_call_action | This action isn't valid for the call's current state (for example, the call has already ended or hasn't been answered yet). | The invite is already being answered, was answered, or was rejected. |
voice:error:media_setup_failed | Failed to answer the call: this device could not open an audio connection to Vonage after 1 attempt, so the call was not answered. Something on the network is blocking real-time audio (WebRTC over UDP), typically a firewall, proxy or VPN. Try another network or allow WebRTC traffic. | Try another network, or allow WebRTC traffic on this one. |
media:error:create_media_error | Failed to answer the call: this device could not open its microphone (<detail>). Check that the app has microphone permission and that no other app is using the microphone, then try again. | Check the microphone permission and that no other app is using the microphone. |
media:error:create_answer_error, process_offer_error | Failed to answer the call: this device could not set up the call's audio (<detail>). Try again; if it persists, contact Vonage support with this error's source. | Try again; if it persists, contact support with the source. |
voice:error:inbound_call_failed | Answering the call failed — it may have already ended, or the media connection could not be established. Please try again. | Any other failure. The cause holds the underlying error. |
Media warnings: onCallMediaWarning
While a call is connected, the SDK compares consecutive audio stats and reports where audio stops, in each direction, through onCallMediaWarning. Each warning is reported once per episode. The call is not ended. Outgoing checks are skipped while muted, and incoming checks while earmuffed.
| Code | Message | Where it fails |
|---|---|---|
media:warning:no_microphone_audio | This device is not capturing any audio from the microphone, so the other party cannot hear you. The microphone may be in use by another app, muted by the operating system, or disconnected. Check the input device and the microphone permission. | This device's microphone |
media:warning:audio_not_sent | The microphone is capturing audio, but this device is not sending it to Vonage. This is a local problem with the device's audio connection; if it persists, end the call and place it again. | This device |
media:warning:audio_not_reaching_vonage | This device is sending audio, but Vonage is not receiving it, so the network is dropping outgoing audio — for example a weak connection or a network change. Check the connection. | The network, device → Vonage |
media:warning:no_audio_from_vonage | No audio is reaching this device from Vonage, so you cannot hear the other party. The network is dropping incoming audio — for example a weak connection or a network change. Check the connection. | The network, Vonage → device |
media:warning:remote_audio_silent | Audio is reaching this device, but it is silent: no sound is arriving from the other party. The problem is between Vonage and the other party's network, not on this device. If it persists, contact Vonage support with this call's id. | The other party, or between Vonage and them |
Hangup reasons
onCallHangup reports why a call ended. The per-platform names are on that page. A call that ended while the device was offline is reported after the SDK reconnects, with every callQuality field 0.
| Reason | Cause | What to do |
|---|---|---|
localHangup | This device hung up. | Nothing. |
remoteHangup | The other party hung up. Also reported for a call that ended while the device was offline when Vonage gave no other outcome. | Nothing. |
remoteReject | The called party rejected the call (REMOTE_REJECTED, SIP 403 / 603). | Nothing. |
remoteNoAnswerTimeout | The called party did not answer in time. | Nothing, or offer to try again later. |
remoteBusy | The called number was busy (REMOTE_BUSY, SIP 486). | Offer to try again later. |
remoteNotFound | The called number does not exist (REMOTE_NOT_FOUND, SIP 404). | Check the number. |
remoteFailure | The carrier or destination failed the call (REMOTE_FAILURE, SIP 5xx). | Try again. If it persists for a destination, contact support with the call ID. |
mediaTimeout | Vonage received no audio from this device, so the media server ended the call. | Check the device's network and microphone. A preceding onCallMediaWarning usually says which. |
Region
If sessions work but calls fail or users cannot be found, check that the SDK's region, your application's Voice region and the region where your users were created are the same. See Region.