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 may be running on the same machine. In this case, you can use ws://127.0.0.1 as the destination; 127.0.0.1 is the IP address of localhost. If it's separate machines, you need to exchange 127.0.0.1 with an reachable IP address of the server, or, some valid DNS name.
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.
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 http://127.0.0.1:9980. The ObjectBox Admin web app should show up. If this fails, check the server's configuration.
Try to reach the Sync port (9999 by default) using a web browser (or a tool cURL): http://127.0.0.1:9999. You should see a short plain text response if this connection is fine.
To check that the hostname is correctly registered, try to connect to the Sync Server using a web browser. You should be able to reach the following addresses: http://your-hostname.com:9980 (the ObjectBox Admin web app) or http://your-hostname.com:9999 (the Sync endpoint). If the pages are loaded and the browser doesn't hang, then your hostname was resolved correctly. You can further investigate hostname issues by using command line tools like
nslookup.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 127.0.0.1 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.
Clients do not connect
If Sync clients do not connect to the server, please doublecheck the Sync Client setup, specifically:
You are using a sync-enabled library of the ObjectBox SDK.
The URL to the Sync Server is correct (see above to ensure the URL is reachable).
Clients connect but do not sync
Can you see the clients connecting to the server in the (debug) logs, but no data is synchronized? Double check that your entity types are sync enabled. If they are not, ObjectBox will store the objects only locally. Follow this checklist:
Did you add a "sync annotation" for the types you want to sync? The Sync Client setup page has the details for the ObjectBox API of the programming language you are using.
Ensure that the generated files data model are up-to-date. Hint: in the model JSON file you should see
"flags": 2for the entity types you want to sync (2is actually a bit flag that enables sync).Ensure that the up-to-date model JSON is also used for the server config.
IDs do not match across devices
You may notice that IDs of objects stored on one device may not always match the IDs on another device. Well, that's not a bug, but a feature. 🙂 Check the docs on Object ID mapping and the possibility to use global IDs instead.
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
Was this helpful?