Troubleshooting Sync

Something is not working? This guide helps to identify typical problems quickly.

How to reach the Sync Server

Sync Clients must specify how to reach the Sync Server. In a test setting, both my be running on the same machine. In this case, you can use ws:// as the destination; is the IP address of localhost. If it's separate machines, you need to exchange with an reachable IP address of the server, or, some valid DNS name.

Using Android emulator? You can use to reach the host (the machine running the emulator). Thus, specify "ws://" in your client if you run the Sync Server on the same machine. For details on Android emulator networking, see here.

Check the network connection

If it looks like data is not synchronized, usually the first thing to check is the network connection between the devices. Usually it's helpful to start the Sync server with the admin web app enabled, so you can e.g. check the connection using the HTTP server URL in the standard browser of clients.

See Sync Server configuration on how to enable HTTP and options.

  1. Using a standard web browser, can you reach the Sync host on port 9980? E.g. first try it on the machine running Sync server via The ObjectBox Admin web app should show up. If this fails, check the server's configuration.

  2. Try to reach the Sync port (9999 by default) using a web browser (or a tool cURL): You should see a short plain text response if this connection is fine.

  3. Next, if the client runs on another machine, check the same ports from client's machine in a web browser. Of course, you need to exchange with an reachable IP address of the server, or, some valid DNS name.

If one of those steps fail, you need to check your network configuration. Like any networking application, ObjectBox Sync relies on a functioning network.

Enable debug logging

The network connection seems fine? OK, let's get additional information! The Sync server comes with a switch to turn on debug logging. Logs go to standard output and are typically very sparse. Debug logs on the other hand provide you with a lot of information. Once you get used to the amount of information, you will learn to identify problems. For example, a client got disconnected? The debug logs usually tell why.

In the ObjectBox Browser, you can enable debug logs in the "Status" page. See Sync Server configuration for details.

Other hiccups

A checklist of other likely issues:

Contact us

The ObjectBox team is here to help you. If you already investigated a bit (e.g. "hey, this debug log there looks odd, no?") it will help to get issues resolved quickly. In any case, do not hesitate to reach out! ❤️

Last updated