Skip to main content

Troubleshooting Guide

There are several possible integration issues that can lead to calls not being established. This section will cover the most frequent ones.

Connection issues

Connection issues usually happen when you provide an invalid token during the SDK setup. When this happens, a web socket connection can't be established with our backend, resulting in errors when trying to connect to a call.

Expired tokens

When you initialize the StreamVideo object, you provide a token, as described here. The tokens generated in the docs have an expiry date, therefore please make sure to always use a token with a valid expiry date. You can check the contents of a JWT token on websites like this one.

Additionally, when expiring tokens are used, you need to provide a tokenProvider when creating StreamVideo, that will be invoked when the existing token expires. This is your chance to update the token by calling your backend.

Wrong secret for token generation

When you start integrating the SDK into your app, you might copy-paste the token from the docs into your project. However, that will not work. Tokens are generated with the help of the app secret (available in your dashboard), and are unique per app id. Your app id is different than the demo apps we have as examples in our docs.

On website like this one, you can verify if the token is signed with the correct signature.

While developing, you can manually generate tokens by providing your secret and the user's ID here. However, note that for production usage, your backend would need to generate these tokens.

User-token mismatch

The token can be valid and correct, but for the wrong user. Make sure that the token you provide matches the id of the user that is used when creating the StreamVideo object.

Third-party network debuggers

There are network debuggers like Wormholy, that allow you to see all the network requests done with your app. However, some of them can interfere and block our web socket connection, like in this case. In order to prevent this, you need to exclude our hosts from debugger tools, as described on the linked issue.

Ringing calls issues

Ringing calls issues usually present themselves in a failure to show the incoming call screen to the user we're trying to call. There are 2 scenarios when an incoming screen is shown:

  • your app is in the foreground and the web socket connection is active. In this case, an in-app ringing screen is shown to the other user.
  • your app is killed or in the background. In this case, you need CallKit integration in order to show the iPhone's native calling screen. Follow these docs for more details on how to accomplish that.

Members in a call

One common issue is that you only specify one user and try to call the same user on another device. This will not work, if you are the caller, you will not receive a notification that you're being called - you can't call yourself.

As you would do it in the real world, you would need to specify another member (or members) that you want to call. Another important note - that member should also exist in Stream's platform (it must have connected at least once). This is needed because we need to know the user's device and where to send the call notification.

Reusing a call id

Call IDs in general can be reused - you can join a call with the same id many times. However, the ringing is done only once per call ID. Therefore, if you implement calls with ringing, make sure that you provide a unique ID every time, in order for the ring functionality to work. One option is to use a UUID as a call ID.

CallKit integration issues

If you followed the CallKit guide, and still have issues, here are some troubleshooting steps:

  • make sure there are no connection issues (see points above)
  • check if the generated VoIP certificate matches the bundle id specified in the dashboard
  • check if the app is using the correct bundle id
  • check if you have created push providers and you specified their correct names when creating the SDK
  • check if you registered the device correctly, by examining whether it's returned in the me response in the connection.ok event
  • check the "Webhook & Push Logs" section on the dashboard to see if there are any push notification failures
  • try sending a hardcoded VoIP notification using a third-party service, to make sure your app integration is correct

Note that if you have failed to report a VoIP notification to CallKit, the operating system may stop sending you notifications. In those cases, you need to re-install the app and try again.


For further debugging, you can turn on more detailed logging. In order to do that, add the following code before the StreamVideo instance is created:

LogConfig.level = .debug

Did you find this page helpful?