Troubleshooting & FAQs

Last updated 2 months ago

While working with Realm Sync, it is likely that you will need to troubleshoot your application. This section aims to provide you with some of the common problems and items to look for when troubleshooting. It is important that you have some kind of error handler for Realm errors within within your application. Instructions on how to do this and details on specific errors can be found here.

Common Issues

A number of common issues are listed below along with some of the items which you will want to research to help resolve your issue.

Unable to synchronize data

  • Is your ROS online and available? You can test the connection with Realm Studio

  • Check both the client and the server logs. Look especially for error level messages that may indicate problems

  • Verify that schema matches between the client and the server

My Mobile Realm database is growing in size

It is not unexpected that a Realm database will grow over time. There are a number of factors that contribute to this. Here are a few details on how to keep your file size at reasonable levels. This normally can be improved in one of two ways.

  1. A Realm reference was not properly closed. See our database docs for more details.

  2. You may need to implement history truncation on your Realm Object Server. Head over to our server docs to learn how to do this

Realm hangs after attempting to open a Realm

Most often this means that you are attempting to asynchronously open a Realm while offline. Either handle within the application logic or switch to using synchronous open (which we recommend using in all cases EXCEPT the very first opening of the Realm). More details can be found here.

Access Token is Expired

It is common to see the following within your server logs: Access token expired (error_code=202)

This is printed on the server as a client tries to access the server with an expired access token. This is typically benign and requires no developer interaction. If the user is still successfully authenticated, a new access token will be automatically granted by the system, and the user will once more have access.

Schema Mismatch

While developing your app, it is inevitable that the schema will change. This can be somewhat tricky for developers as Realm sync allows additive-only schema changes by default. This means that changing the schema in a non-additive way (i.e. turning a string property into an integer property) can cause the schema in your client and server to mismatch. To resolve this, either redefine your client schema to match the server schema or delete and recreate the Realm with the mismatched schema (note: deleting your server Realm will result in a loss of data if not backed up or copied into a new Realm). Realm Studio is a great tool for both of these tasks as it allows you to export the server schema in your language of choice and gives you the ability to delete Realms.

It is also important to note that schema changes work very differently with synced Realms then local non-synced Realms. More details can be found here.

HTTP Upgrade Failed

When a mobile client tries to sync data, it first makes an HTTP(s) request to the server. When this request is received, it attempts to upgrade the connection between the client and server to a Websocket, which is the backbone of the sync process. If this process fails, you may see an error like this in the log. This is typically benign, and will often resolve itself on a retry. If this continues to happen for an extended period of time, it could indicate server unavailability or because of intermediate proxy that is interrupting the connection.

Additional Errors

A more complete list of errors can be found within the Errors section of our Using Synced Realms documentation

Information to Gather

While troubleshooting, you will want to gather more information to help pinpoint where the exact issue is. This is also imperative if reaching out for more help on the forums, Github, or through our support channel. Helpful information may include:

  • Versions: client SDK and server

  • Client and server logs - debug level or higher is typically recommended for advanced troubleshooting

  • Error messages

  • Background: when did the behavior start occurring? What has changed since the behavior began?

  • What type of sync are you using? (full or query-based) Are you using the correct APIs?

  • How often is the issue happening? Approximately how many users are using the app concurrently?

Getting Help

Having an issue with Realm Platform that you don't feel you can solve from the documentation? There are a number of avenues for you: