Skip to main content


Ditto won't sync

If you are having trouble synchronizing devices in Ditto, follow this guide.

Synchronization seems slow, or comes to a halt over time

Ensure that you are only creating a fixed number of live queries. Each live query will

General diagnostics

  1. Set DittoLogger.minimumLogLevel = DittoLogLevel.VERBOSE before you initialize Ditto(identity).
  2. Look at the logs. Do you see any helpful errors or warnings?
  3. Verify that your app id is the same on all devices


  1. Turn Use Location on
  2. Turn Bluetooth Scanning on
  3. Are permissions set correctly? See installation.
  4. Go to your OS-level permissions for Bluetooth and clear the app permissions for your application.
  5. Delete the app, install it again, and open it. Does it ask for Bluetooth permissions?
  6. Android only: are you calling ditto.refreshPermissions()?
  1. Are permissions set correctly? See installation.
  2. Go to your OS-level permissions and clear the app permissions for your application.
  3. Delete the app, install it again, and open it. Does it ask for location permissions?
  4. If you are using a custom TransportConfig, make sure you have enabled all peer-to-peer transports using enableAllPeerToPeer().

Local Area Network (LAN)

  1. Are permissions set correctly? See installation.
  2. Are both devices connected to the same WiFi network?
  3. Check your router settings and see the LAN troubleshooting guide.

Online Playground

Did you copy your playground token and App ID correctly?

  1. Login to the Portal
  2. Go to your App.
  3. Make sure that the portal playground token is the same as the value you are using in your code.

Online Playground enabled in the Ditto Portal

Did your device connect to the internet?

OnlinePlayground applications must connect to the Big Peer first before going offline. Read more about online playground.

If your app need full offline access without ever connecting to the Internet, please request an offline license token.

Do you have a firewall or proxy enabled that is blocking Ditto's connection to the Big Peer?

Verify that you can reach the following endpoints. You should see the output exactly as written below:

> nc -v 443Connection to port 443 [tcp/https] succeeded!^C
> curl -i 405 Method Not AllowedDate: Fri, 30 Sep 2022 02:03:36 GMTContent-Type: text/plain; charset=utf-8Content-Length: 23Connection: keep-aliveAccess-Control-Allow-Origin: *Access-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, PUT, POST, DELETE, PATCH, OPTIONSAccess-Control-Allow-Headers: X-DITTO-ENSURE-INSERT,X-HYDRA-ENSURE-INSERT,X-DITTO-CLIENT-ID,X-HYDRA-CLIENT-ID,Accept,Referer,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,X-Forwarded-ForAccess-Control-Max-Age: 1728000
HTTP method not allowed% 

If this test passes, next check to see if WebSockets are blocked on your machine. Some corporate networks, firewalls, or proxies block the HTTP upgrade packet that tells the WebSocket server to keep the connection alive. Check with your IT administrator to see if your computer is configured to block WebSocket connections.

Online with Authentication

  1. Did you follow the tutorial?
  2. Is the website address behind https and available on the open Internet?
  3. Verfiy that your server is reachable by the Big Peer at and
  4. Are you implementing the authentication expiring soon delegate?
  5. Verify that your webhook provider name is correctly copied in the Ditto portal.

Offline Playground and Shared Key

  1. Login to the Ditto Portal.
  2. Check the value of your offline license token in the Ditto Portal. Is the offline license token expired?
  3. Is the offline license token copied correctly?
  4. Is the shared key copied correctly? Generate a new shared key.

Still having trouble?

  1. Are you creating many live queries? Reduce the number of live queries in your app.

Email us at or login to your Ditto account to chat with the support bot in the lower right corner of your screen. An engineer will reach out to you shortly.