Troubleshooting Guide

Refer to any of the following to help you get back on track:

If you need technical support, submit a technical support request ticket. (See Contact Us)

Obtaining and Analyzing the Debug Logs

Synchronizing seems slow or comes to a halt over time

App is using too much memory, why?

Debugging Blocked Transactions

Causes of Blocked Transactions

Android App Store Submission Issues

Subscription Server Overload (503 Errors)

iOS mDNS Stale Record Crashes

Still stuck?

SDK crash: mDNS index out of bounds (4.11 and earlier)

Obtaining and Analyzing the Debug Logs

To troubleshoot a peer-to-peer data sync issue, first determine the cause of the issue by obtaining and analyzing the database error and warning messages captured in the debug logs.

Setting the Logs to Debug Level

As demonstrated in the following snippet, obtain the database debug logs before Ditto is initialized so that any potential issues related to the file system access and authentication background tasks that run during initialization are tracked. You want to begin gathering logs before Ditto is initialized in order to capture any potential issues with those two background tasks.

DittoLogger.minimumLogLevel = .debug
let ditto = Ditto(identity: .onlinePlayground(
    appID: "REPLACE_ME_WITH_YOUR_APP_ID",
    token: "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN"
))
do {
  try ditto.startSync()
} catch (let err) {
  print(err.localizedDescription)
}

try {
    val androidDependencies = DefaultAndroidDittoDependencies(context)
    val identity = DittoIdentity.OnlinePlayground(
        androidDependencies,
        appId = "REPLACE_ME_WITH_YOUR_APP_ID",
        token = "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN"
    )
    DittoLogger.minimumLogLevel = DittoLogLevel.DEBUG
    ditto = Ditto(androidDependencies, identity)
    ditto.startSync()
} catch (e: DittoError) {
    Log.e("Ditto error", e.message!!)
}

import { init, Ditto, Logger } from "@dittolive/ditto"

// Set the Ditto log level to Debug
Logger.minimumLogLevel = 'Debug'

const identity: Identity = {
  type: 'onlinePlayground',
  appID: 'REPLACE_ME_WITH_YOUR_APP_ID',
  token: 'REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN'
}

const ditto = new Ditto(identity, './your-ditto-application-data-path')
ditto.startSync()

DittoDependencies androidDependencies = new DefaultAndroidDittoDependencies(this.context);

// Set the Ditto min log level to Debug
DittoLogger.setMinimumLogLevel(DittoLogLevel.DEBUG);

try {
    ditto.startSync();
} catch(DittoError e) {
    //handle error
}

try
{
    DittoLogger.SetMinimumLogLevel(DittoLogLevel.Debug);
    var ditto = new Ditto(DittoIdentity.OnlinePlayground("REPLACE_ME_WITH_YOUR_APP_ID", "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN", true), path);
    ditto.StartSync();
}
catch (DittoException ex)
{
    Console.WriteLine($"Ditto Error {ex.Message}");
}

try
{
    DittoLogger.SetMinimumLogLevel(DittoLogLevel.Debug);
    var ditto = new Ditto(DittoIdentity.OnlinePlayground("REPLACE_ME_WITH_YOUR_APP_ID", "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN", true), path);
    ditto.StartSync();
}
catch (DittoException ex)
{
    Console.WriteLine($"Ditto Error {ex.Message}");
}

use dittolive_ditto::prelude::*;
use dittolive_ditto::identity::get_development_provider;
use std::time::Duration;

DittoLogger::set_minimum_log_level(LogLevel::Debug);

let config = DittoConfig::new(
    std::env::var("DITTO_APP_ID").expect("DITTO_APP_ID must be set"),
    DittoConfigConnect::Server {
        url: std::env::var("DITTO_URL")
            .expect("DITTO_URL must be set")
            .parse()
            .unwrap(),
    },
);

let ditto = Ditto::open_sync(config)?;

let auth = ditto.auth().expect("Auth is available in Server mode");
auth.set_expiration_handler(async |ditto: &Ditto, _duration: Duration| {
    if let Some(auth) = ditto.auth() {
        let token = std::env::var("DITTO_PLAYGROUND_TOKEN")
            .expect("DITTO_PLAYGROUND_TOKEN must be set");
        let provider = get_development_provider();
        if let Err(e) = auth.login(&token, &provider) {
            eprintln!("Authentication failed: {}", e);
        }
    } else {
        eprintln!("Ditto authentication not configured");
    }
});

ditto.sync().start()?;

ditto.SetMinimumLogLevel(ditto.LogLevelDebug)

config := ditto.DefaultDittoConfig().
    WithDatabaseID("REPLACE_ME_WITH_YOUR_APP_ID").
    WithConnect(&ditto.DittoConfigConnectServer{URL: dittoAuthURL})

dit, err := ditto.Open(config)
if err != nil {
    log.Fatalf("error: failed to open Ditto: %v\n", err)
}
defer dit.Close()  // cleanup

dit.Auth().SetExpirationHandler(
    func(d *ditto.Ditto, timeUntilExpiration time.Duration) {
        clientInfoJSON, err := d.Auth().Login(
            "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN",
            ditto.DevelopmentAuthenticationProvider(),
        )
        if err != nil {
            log.Errorf("error: expiration handler: %v\n", err)
        } else {
            log.Printf("info: expiration handler: logged in; client info: %v\n", clientInfoJSON)
        }
    })

if err := dit.Sync().Start(); err != nil {
    log.Errorf("Unable to start sync: %v\n", err)
}

Authentication

For server connection mode with custom authentication identities, the first thing that Ditto needs to do is authenticate to the Big Peer. Confirm that all devices share the same AppID by verifying that the app_id log line contains your AppID:

JSON

Ditto::new_from_uninit_ditto; app_id = 22389e28-9590-4cbf-b683-b3ac5ab2269e; site_id = 13769592724050309105; history_tracking = Disabled; presence_broadcast_targets = SmallPeersOnly

Once confirmed, verify that authentication was successful.

JSON

AuthClient: authentication request succeeded

Once authentication is successful, client re-authentication does not occur until the device’s local certificate expires, as indicated by the following:

JSON

AuthClient: refreshing token in 302399 seconds

Incorrect APP ID

If the appID or token are incorrect, the following displays in the debug logs:

JSON

AuthClient: failed to get JSON for auth response; e = reqwest::Error { kind: Decode, source: Error("expected value", line: 1, column: 1)

JSON

AuthClient: No valid Web token present. Can not request certificate.
AuthClient: failed to obtain a certificate ValueNotFound

See if the following fixes your issue:

Log in to the Portal
Go to your App.
Copy the AppID and Playground Token and use it in your Ditto initialization.

Outdated certificate

JSON

[DEBUG] 2023-08-03T17:36:35.046Z: failed to connect to peer; error = Connect failed because a TLS stream couldn't be established: invalid peer certificate contents: invalid peer certificate: UnknownIssuer; remote_peer = MulticastRemotePeer(id: 10, announce Q2RLCGEYdpLwjFditto)

If you see the above message, your device’s locally cached certificate is invalid. The device needs to call ditto.auth.logout() and reconnect to the Internet to get a new certificate. Alternatively, you can clear the local cache by reinstalling the mobile application or clearing the local persistence directory.

Authentication server unavailable

Shell

Error attempting authentication with token: Could not connect to authentication server

Shell

Error attempting authentication with token: Failed to authenticate: Internal server error; debug: Some("Ditto cloud failed to decode the response body.  This is most likely due to malformed JSON in the response: error decoding response body: expected value at line 1 column 1"); client info: None

If you see either of the above messages, this is most likely a problem with your authentication webhook. There is a debugging level log line that will provide more information about the authentication webhook if you need more information. Send a POST request with a JSON stringified body to your server to ensure that the AWS-hosted Big Peer servers located in U.S. regions successfully send POST requests to your authentication server.

Shell

curl -x POST https://my.webhook.com

Ditto closing prematurely

If you see that Ditto is unable to sync, and see the log lines below, it’s possible that your ditto instance is being deallocated before it is able to synchronize with other peers. Ensure that the ditto instance is initialized and saved in a global variable that is long-lived for the duration of the application.

Shell

[DEBUG] 2024-06-06T23:45:29.634Z: Shutting down Ditto
[INFO] 2024-06-06T23:45:29.634Z: Peer shutting down
[DEBUG] 2024-06-06T23:45:29.634Z: stopping HTTP server
[DEBUG] 2024-06-06T23:45:29.634Z: stopping TCP server
[INFO] 2024-06-06T23:45:29.634Z: Peer shutdown done
[DEBUG] 2024-06-06T23:45:29.634Z: Ditto shutdown complete
[DEBUG] 2024-06-06T23:45:29.634Z: Deallocating Ditto

Common mistakes

authenticationExpiringSoon and authenticationRequired both need to be implemented according to the sample code.
Since callback objects are only invoked when Ditto initializes and the client authentication certificate expires, do not create subscriptions inside callbacks.
Keep a strong reference to the AuthClient for the duration of the Ditto object, otherwise the auth handler will become garbage collected at an inappropriate time.
Verify that your webhook provider name is correctly copied in the Ditto portal.
The provider name given to the Ditto Client must match a provider name in the Portal (e.g., my-auth).

Is your AuthClient becoming garbage collected?

Ensure that you keep a reference to the AuthClient in scope for the duration that Ditto is also active. You should attach the dittoAuth variable to the object so it does not get garbage collected. For example:

namespace Sync {
    public class DittoClient {
        private Ditto ditto;
        private DittoAuthDelegate dittoAuthDelegate;

        public DittoClient(string appId, string id, string jwt) {
           dittoAuthDelegate = new DittoAuthDelegate(id, jwt);
           ditto = new Ditto(identity);
        }
       ...
   }
}

Syncing With Big Peer

A small peer syncs with the Big Peer using a WebSocket connection. The debug logs will tell you each step to create a successful WebSocket connection to the big peer. First, the peer will discover the big peer and you’ll see a Discovered event.

JSON

peer_event = Discovered(WebsocketClientPeer(WebsocketClientRemotePeer { id: 4, transport_id: 3, local_announce: LocalAnnounceData { outer_protocol_version: 50, os: Generic, network_id: 2383820004, query_overlap_group: None, device_name: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537" }, connect_address: "wss://<your-big-peer-host>", routing_hint: RoutingHint(0), condition_sender: UnboundedSender { chan: Tx { inner: Chan { tx: Tx { block_tail: 0x242120, tail_position: 0 }, semaphore: Semaphore(0), rx_waker: AtomicWaker, tx_count: 2, rx_fields: "..." } } } }))

If the WebSocket connection that links the Small Peer to the Big Peer is successful, the debug logs contain the ConnectionEstablished event:

JSON

peer_event = ConnectionEstablished(PeerConnection { id: 4, connection_type: WsClient, remote_announce: Announce { outer_protocol_version: Some('2'), os: Some(Linux), network_id: Some(1356909299), query_overlap_group: None, device_name: Some("Ditto Cloud") }, remote_peer_id: SiteIdAndPubKey([...])

If you see StreamFailed or ConnectionEnded or any errors related to WebSocket connection with the Big Peer, there is likely an error in the Big Peer subscription server. For troubleshooting help, contact Ditto support.

Subscription Server Overload (503 Errors)

If Small Peers repeatedly fail to connect to the Big Peer with 503 Service Unavailable errors, the Big Peer subscription server may be overloaded. In the debug logs, you will see the connection cycle repeatedly through Discovered → ConnectionEstablished → ConnectionEnded with errors like the following:

JSON

failed to connect to peer error=Custom Transport Error: HTTP error: 503 Service Unavailable

Common cause: Subscription queries with deeply nested predicates or complex nested object structures in WHERE clauses can exceed the subscription server’s processing limits. This is more likely with large collections (tens of millions of documents) where complex queries must evaluate against many documents. Programmatically generated subscription queries are a frequent source of excessive nesting. What to check:

Review the subscription queries in your debug logs (see the Subscriptions section above) for queries with many nested elements in their WHERE clauses.
Look for subscription queries generated programmatically that may produce deeply nested predicates.
Check whether the 503 errors correlate with specific subscription query registrations — the issue may begin when a particular subscription is created.

What to do:

Simplify subscription query predicates — flatten nested conditions where possible.
If you cannot identify which query is causing the issue, contact Ditto support with your debug logs so engineering can investigate server-side.
Ensure you are running the latest Big Peer version, as improvements to subscription server stability are ongoing.

Corrupted certificate

If your certificate chain is corrupted, you will see the following.

JSON

Connect failed because the underlying websocket transport reported an error: TLS error: webpki error: UnsupportedCriticalExtensio

To fix this, please try to reset your certificate chain. On MacOS, open the Keychain Access application and navigate to the settings, and click “Reset default keychains…”

JSON

Keychain.app > Settings > Reset Default Keychains

You will then see that the underlying physical replication session has been started with phy started. The pkSOME_BYTES identifier displays the public key to the Big Peer instance that a Small Peer WebSocket connection has temporary sync access. Note that the following snippet is merely an example; the pkSOME_BYTES identifier is not a guaranteed static variable.

JSON

phy started; remote = pkAocCgkMCh0wD6Y83qm2UHtiN6264Jivvimg6xdR778ODaKODFKw

Once temporary remote access is authorized, the following debug log message appears to indicate that the Small Peer (client) WebSocket connection to the Big Peer (cloud server) is successful:

JSON

VirtConnElectedNewConn { new_conn: Some((4, WsClient)), old_conn: None }

Permissions and Subscriptions

For the Small Peer to have an active subscription to read and write to other peers, it must first be authorized access by a Big Peer. If the Small Peer does not have permissions to access database replication, it cannot subscribe to its collections to read and write.

Permissions

Given this, before you check the Small Peer’s active read-write subscriptions, confirm that the Small Peer has permissions to access the database.

JSON

local permission: Permission {
    read: PermissionRules { everything: true, queries_by_collection: {} },
    write: PermissionRules { everything: true, queries_by_collection: {} }
},
remote permission: Permission {
    read: PermissionRules { everything: true, queries_by_collection: {} },
    write: PermissionRules { everything: true, queries_by_collection: {} }
}

Local permissions refer to the current peer that is running on the device. Once the peer is authorized, it will begin to print the active subscriptions. Ditto will print the active subscriptions every time the sync engine wakes up. This includes a local write to the database or a sync event from another peer writing to their local database. You will want to verify that these permissions are correct and what you expect. A peer cannot subscribe to a collection if it does not have read permission. The default Big Peer remote permission to access a connected Small Peer local database replication to read and write is as follows:

JSON

write: { everything: true, queries_by_collection: {} }
read: { everything: true, queries_by_collection: {} }

Subscriptions

Now that default permissions are verified, confirm that the Big Peer is connected to a Small Peer and the local-to-global database replication task is running. Ditto prints a list of all the queries that the peer is currently subscribed to.

JSON

local subscription: Subscription { everything: false, queries: {"__presence": {Query { expr: "_id != '13407763363308666127' && v == 3 && t > 1682717143093", order_by: [], limit: None, offset: None }}, "tasks": {Query { expr: "isDeleted == false", order_by: [], limit: None, offset: None }}} }, remote subscription: Subscription { everything: true, queries: {} }

By default, each peer includes some internal subscriptions, which are denoted using a double underscore (__) before the collection name; for example, the following default internal __presence subscription:

JSON

{"__presence": { expr: "_id != '13407763363308666127' && v == 3 && t > 1682717143093", order_by: [], limit: None, offset: None }}

You will also see a list of remote subscriptions. The big peer subscribes to everything, so you will see the following line which references the big peer:

JSON

remote subscription: Subscription { everything: true, queries: {} }

If there are any application-level subscriptions, they will be listed by collection. For instance, if a Small Peer that subscribes to all tasks that are not deleted, the following appears:

JSON

"tasks": {Query { expr: "isDeleted == false", order_by: [], limit: None, offset: None }}}

If a subscription changes, the following appears:

JSON

Application: notifying a local subscription change

If you have problems with subscriptions or permissions, you can try the operations with global read and write permission to verify that sync succeeds in this case. Check the following

Do your permissions match your subscriptions? If you do not have permission to subscribe to data, it will not sync to the device.
Are you subscribing to what you expect to see?
Do you have more subscriptions than you expect to have?
Do your live queries match the subscriptions?

Query Parsing Errors

ditto.store.collection("myCollection").find("").subscribe() // -> ParseError

ditto.store.collection("myCollection").find("").subscribe() // -> ParseError

ditto.store.collection("myCollection").find("").subscribe() // -> ParseError

ditto.store.collection("myCollection").find("").subscribe() // -> ParseError

ditto.store.collection("myCollection").find("").subscribe() // -> ParseError

ditto.store.collection("myCollection").find("").subscribe() // -> ParseError

ParseError can be printed in the debug logs when there is a problem with your query. For example, if you create a subscription in Swift that is the empty string, you will see a ParseError in the logs.

Writes

If a Write is made to the local database, the following debugging messages appear:

JSON

Write txn committed; txn_id = 40; originator = User

JSON

Notifying a database change; transaction = 40

Once a Write is made to the local database, Ditto re-prints the active subscriptions and permissions to access the debug log, as demonstrated in the previous snippet. Next, the Small Peer creates the “update file.” Annotated in the debug logs as follows, the update file provides the status of the data update and, using the pkA and pkB identifiers, indicates the two peers involved in the data exchange.

JSON

Creating a sending update, sending_update_path = "pkA/pkB/sending_update"

Once the local peer finishes creating the update file, the following appears to indicate that the update file is complete and the local peer is ready to send the new update to the remote peer. Note that at this time the local Write has yet to be synchronized across all connected peers.

JSON

update creation done; since_index = 40; new_update_created = true; num_docs = 1; elapsed = 908us 708ns

If the local peer has received the update, all connected peers are synchronized, and the local database replication process is complete, the following appears:

JSON

No next update chunk to send - setting is_ready to false
No message to send

Did your device connect to the internet?

Server authenticated applications must connect to Ditto Server first before going offline.

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

A proxy may either block connections or cause errors in the log by substituting its own TLS certificate: invalid certificate: UnknownIssuer. If you see this log message you will either need to get Ditto unblocked or add the CA certificate to the Small Peer’s trusted certificate store. Verify that you can reach the following endpoints (replace REPLACE_ME_WITH_YOUR_URL_HOST with the host of your URL from the Ditto Portal, Connect via SDK). You should see output similar to below:

JSON

> nc -v REPLACE_ME_WITH_YOUR_URL_HOST 443
Connection to REPLACE_ME_WITH_YOUR_URL_HOST port 443 [tcp/https] succeeded!
^C

JSON

> curl -i https://REPLACE_ME_WITH_YOUR_URL_HOST/_ditto/auth/login
HTTP/1.1 405 Method Not Allowed
Date: Fri, 30 Sep 2022 02:03:36 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 23
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, PUT, POST, DELETE, PATCH, OPTIONS
Access-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-For
Access-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.

Connection issues

If you are unable to see connections over particular transports, first ensure you are following the SDK Setup guide for your language.

Swift

Kotlin

JavaScript Web | Node.js | React Native

Bluetooth on Linux

After you verify that your app is set up correctly, if connection issues continue follow these debugging steps.

Bluetooth

Turn Use Location on
Turn Bluetooth Scanning on
Are permissions set correctly? See
Go to your OS-level permissions for Bluetooth and clear the app permissions for your application.
Delete the app, install it again, and open it. Does it ask for Bluetooth permissions?

Apple Wireless Direct Link, P2P-Wifi, Wifi Aware

Go to your OS-level permissions and clear the app permissions for your application.
Delete the app, install it again, and open it. Does it ask for location permissions?
If you are using a custom

Local Area Network (LAN)

Are permissions set correctly? See
Are both devices connected to the same WiFi network?
Check your router settings and see the
If your device has VPN enabled, then peers can fail to communicate. Ensure that your VPN supports UDP multicasting.

Debugging Blocked Transactions

This section only discusses blocked transactions on native platforms (e.g. iOS, Android, Windows, Linux). Ditto in web browsers operates sufficiently differently and isn’t covered here.

Blocked write transactions will automatically retry until they succeed. A blocked write transaction will never crash. However, blocked write transactions are a common cause for poor database performance. Long running blocks are generally bad since they mean that nothing else can be writing to the database during this time. This could manifest itself as one of many problems:

Unresponsive UI: an interaction might try to update a document, but is blocked by an existing write transaction
Slow sync: new updates cannot be integrated into the store, since they’re blocked by another write transaction

A blocked write transaction can hint that something is wrong with the application code, or at a deeper level in Ditto. This page contains some tips & tricks to help understand the situation. The process of unblocking is automatic and you don’t need to write any code to handle this. However, you can drastically reduce the chance of blocking transactions by making sure a device is only syncing the data it really needs.

Did your certificate expire and fail to refresh?

When using OnlineWithAuthentication,

Send a POST request with a JSON stringified body to your server to ensure that Ditto Server successfully sends POST requests to your authentication server.

authenticationExpiringSoon
Since callback objects are only invoked when Ditto initializes and the client authentication certificate expires, do not create subscriptions inside callbacks.
Keep a strong reference to the AuthClient for the duration of the Ditto object, otherwise the auth handler will become garbage collected at an inappropriate time.

Verify that your webhook provider name is correctly copied in the Ditto portal

The provider name given to the Ditto Client must match a provider name in the Portal (e.g., my-auth).

Is your AuthClient becoming garbage collected?

pseudocode

namespace Sync {
    public class DittoClient {
        private Ditto ditto;
+       private DittoAuthDelegate dittoAuthDelegate;

        public DittoClient(string appId, string id, string jwt) {
+          dittoAuthDelegate = new DittoAuthDelegate(id, jwt);
           ditto = new Ditto(identity);
        }
       ...
   }
}

Bluetooth

Turn Use Location on
Turn Bluetooth Scanning on
Are permissions set correctly? From SDK Setup Guides, refer to the installation article for your language
Go to your OS-level permissions for Bluetooth and clear the app permissions for your application.
Delete the app, install it again, and open it. Does it ask for Bluetooth permissions?
Android only: are you calling ditto.refreshPermissions()?

Apple Wireless Direct Link, P2P-Wifi, Wifi Aware

Are permissions set correctly? (From SDK Setup Guides, refer to the installation article for your language)
Go to your OS-level permissions and clear the app permissions for your application.
Delete the app, install it again, and open it. Does it ask for location permissions?
If you are using a custom TransportConfig, make sure you have enabled all peer-to-peer transports using enableAllPeerToPeer().

Local Area Network (LAN)

Are permissions set correctly? From SDK Setup Guides, refer to the installation article for your language)
Are both devices connected to the same WiFi network?
Check your router settings and see Lan Optimizations
If your device has VPN enabled, then peers can fail to communicate. Ensure that your VPN supports UDP multicasting.

Slow Initial Sync from Ditto Server

When initial sync from the Ditto Server (Big Peer) takes significantly longer than expected — for example, 15–20 minutes or more — the issue may be caused by server-side resource constraints rather than client-side problems.

Symptoms

Initial sync from the server takes significantly longer than expected, but subsequent syncs are fast
Intermittent authentication failures (AuthClient: failed to obtain a certificate) that resolve on retry
Debug logs show repeated offset retransmission or StreamFailed / ConnectionEnded events during initial sync

Common Causes

Disk IOPS constraints: The Ditto Server instance may have insufficient disk I/O throughput to serve large initial sync payloads under load. This is more common on shared cloud instances serving multiple apps.
Load balancer issues: In rare cases, a transport pod behind the load balancer may silently drop connections while reporting healthy status, causing sync retries and delays.

Resolution

Set a routing hint: If your app uses multiple sites or locations, set a routingHint in your transport config to help the server co-locate related peers. This reduces overhead during initial sync. See Optimizing Server Performance for code samples.
Use routing hints alongside sync subscriptions: Setting a routing hint is especially important when the Big Peer is resource-constrained. The routing hint helps the server prioritize and route sync traffic efficiently.
Contact Ditto support: If symptoms persist after setting routing hints, the server instance may need an IOPS or memory allocation increase. Contact Ditto support with your app ID and a description of the sync delays.

These server-side resource constraints do not affect peer-to-peer sync between Small Peers. If devices sync quickly with each other but slowly from the server, this is a strong indicator of a server-side issue.

iOS mDNS Stale Record Accumulation

On iOS, if a device disconnects abruptly (for example, due to a crash, power loss, or sudden loss of Wi-Fi), it may fail to withdraw its mDNS records. Each unclean disconnect can leave behind stale IPv6 link-local address records. Over time, these stale records accumulate, and other peers attempt to connect to all advertised addresses — including the stale ones. When many stale records build up for a single peer, the resulting flood of failed TCP connection attempts (each returning No route to host / OS error 65) can cause excessive resource consumption. On memory-constrained iOS devices, this can lead to app crashes. Symptoms:

Repeated No route to host (OS error 65) errors in debug logs
High rate of failed connection attempts (hundreds per minute)
App crashes on lower-specification iOS devices, especially during peak usage
One peer showing an unusually large number of IPv6 link-local addresses in mDNS records

Resolution:

Reboot affected devices

Reboot the device that is advertising stale mDNS records. This flushes the stale mDNS cache and forces a clean re-announcement.

Reduce TCP connect timeout

If the issue recurs, reduce the TCP connect timeout so that connection attempts to stale addresses fail faster instead of tying up resources. Set the system parameter before starting sync:

ALTER SYSTEM SET transport_tcp_connect_timeout = 5000

This sets the timeout to 5000 milliseconds (5 seconds), allowing the SDK to abandon unreachable addresses more quickly.

Upgrade the SDK

Upgrade to SDK version 4.14.4 or later, which includes mDNS stability improvements that reduce stale record accumulation.

To identify which device is advertising stale records, examine the IPv6 link-local addresses in the mDNS responses using Wireshark. A device with significantly more address records than expected is likely the source.

Synchronization seems slow, or comes to a halt over time

Ensure that you are only creating a fixed number of live queries, with a smaller amount of data.
Avoid using LIMIT or ORDER BY with mutable fields in subscription queries. See Stateful Subscription Performance Guidelines for details.
Evict irrelevant data. You can evict all irrelevant data once per day
Turn off verbose logging. Verbose logging can slow down replication considerably, especially with thousands of documents. Hence, it could look like that sync is stalling, but that can be indistinguishable from the logging mechanism slowing down ditto because it is trying to write too many lines.
Look at the size of your ditto directory. Is it very large? Large databases will be slower. Try to query less data.

App is using too much memory, why?

Use profiling tools for your platform to better understand where the memory leak may be occurring.
Ensure you are not loading too much data into memory at once. Ditto is designed to work with large datasets, but you should only load the data you need at any given time.
A common issue we see in reactive apps is a failure to dispose of resources as conditions change. Your app could create a large accumulation of publishers that infinitely grow. Every liveQuery and subscription in ditto must be explicitly stopped using the stop or cancel API. See syncing data for more information.

Debugging Blocked Transactions

This section only discusses blocked transactions on native platforms (e.g. iOS, Android, Windows, Linux). Ditto in web browsers operates sufficiently differently and isn’t covered here.

Unresponsive UI: an interaction might try to update a document, but is blocked by an existing write transaction
Slow sync: new updates cannot be integrated into the store, since they’re blocked by another write transaction

A blocked write transaction can hint that something is wrong with the application code, or at a deeper level in Ditto. This page contains some tips & tricks to help understand the situation. The process of unblocking is automatic and you don’t need to write any code to handle this. However, you can drastically reduce the chance of blocking transactions by making sure a device is only syncing the data it really needs.

What is a “blocked” transaction?

At any given time, there can be only one write transaction. Any subsequent attempts to open another write transaction will become blocked until the existing write transaction finishes.

Read vs. Write Transactions

Read transactions operate differently to write transactions. Read transactions cannot be blocked and can run in parallel with write transactions. Read transactions don’t block each other, don’t block write transactions, and aren’t blocked by write transactions. If a write transaction is blocked, Ditto will log a message with increasing severity every 10s.

Time (t) a transaction has been blocked	Log Level
t ≤ 30s	DEBUG
31s < t ≤ 120s	WARN
120s < t	ERROR

To see these logs in the database, it’s important to have a minimum log level set. Transactions that are blocked for over 2 minutes should always be visible in the logs. If INFO level is used, then INFO, WARN, and ERROR messages will all be included in the logs. This means any write transactions blocking for more than 30s should always be visible in the logs.

Reading the Logs

If a write transaction is blocked, the device logs will look something like the following. In this example we can see a write transaction was blocked for a total of 150s (or 2.5 minutes).

As time progressed, Ditto complained more and more loudly (starting with DEBUG logs before eventually logging at ERROR level). Eventually the existing transaction finished and blocked transaction was able to proceed. The write transaction which was blocked was for a Ditto internal component. This is identified by “originator=Internal”. The existing, long-running write transaction which was causing the block was a user call in the public SDK. This is identified by “blocked_by=User”. So a user-level write transaction is blocking some internal workload. This is not necessarily a problem, as the internal system will catch up eventually.

Originators

The three values you’ll see for originator and blocked_by are:

Originator / Blocked By	Description
”User”	Any user-level API which modifies data.
”Internal”	An internal job (presence data, DB maintenance, etc.).
”Replication”	Updating the store with data received via replication.

Causes of Blocked Transactions

This section presents a few example blocked transaction scenarios, how they would appear in logs, and what they might mean.

User blocks User

An application might block its own write transactions by performing multiple writes at the same time in different places. If one is slow (perhaps it does too much work, or perhaps it reaches out to external APIs, etc.) then the other write transactions will block until it finishes.

// Thread/Queue 1 (starts first):
{
    // Somewhere in the app, a long running write transaction exists
    ditto.store["people"].findByID(docID).update { mutableDoc in
        // Most update tasks are quick, but a developer might
        // doing something slow within the update block:
        let apiData = getDataFromASlowExternalAPICall() // <-- !!!!

        mutableDoc?["age"] = apiData.age
        mutableDoc?["ownedCars"].set(DittoCounter())
        mutableDoc?["ownedCars"].counter?.increment(by: apiData.count)
    }
}

// Thread/Queue 2 (starts second):
{
    // Somewhere else in the app, concurrently (e.g. background thread or queue)
    // another write transaction tries to update a document.
    //
    // This will block until the "people" update block above completes.
    let docID = try! ditto.store["settings"].upsert([
        "_id": "abc123",
        "preference": 31,
    ])
}

// Thread/Queue 1 (starts first):
{
    // Somewhere in the app, a long running write transaction exists
    ditto.store["people"].findById(docId).update { mutableDoc ->
        // Most update tasks are quick, but a developer might
        // doing something slow within the update block:
        val apiData = getDataFromASlowExternalAPICall() // <-- !!!!

        mutableDoc?.let { doc ->
            doc["age"] = apiData.age
            doc["ownedCars"].set(DittoCounter())
            doc["ownedCars"].counter?.increment(amount = apiData.count)
        }
    }
}

// Thread/Queue 2 (starts second):
{
    // Somewhere else in the app, concurrently (e.g. background thread or queue)
    // another write transaction tries to update a document.
    //
    // This will block until the "people" update block above completes.
    val docId = try! ditto.store["settings"].upsert(
        mapOf(
            "_id" to "abc123",
            "preference" to 31,
        )
    )
}

// CompletableFuture 1 (starts first):
CompletableFuture.supplyAsync(() -> {
    // Somewhere in the app, a long running write transaction exists
    // Most update tasks are quick, but a developer might be
    // doing something slow within the transaction:
    return getDataFromASlowExternalAPICall(); // <-- !!!!
}).thenCompose(apiData -> {
    Map<String, Object> args = new HashMap<>();
    args.put("docId", docId);
    args.put("age", apiData.getAge());
    args.put("count", apiData.getCount());

    return ditto.getStore().execute(
        "UPDATE people SET age = :age, ownedCars = ownedCars + :count WHERE _id = :docId",
        args
    );
});

// CompletableFuture 2 (starts second):
CompletableFuture.supplyAsync(() -> {
    // Somewhere else in the app, concurrently (e.g. background thread)
    // another write transaction tries to update a document.
    //
    // This will block until the "people" update above completes.
    Map<String, Object> doc = new HashMap<>();
    doc.put("_id", "abc123");
    doc.put("preference", 31);

    Map<String, Object> args = new HashMap<>();
    args.put("doc", doc);

    return ditto.getStore().execute("INSERT INTO settings VALUES (:doc)", args);
});

SDK crash: mDNS index out of bounds

Symptom: The SDK crashes with a panic containing index out of bounds in the mdns_sd library stack trace. The crash typically occurs shortly after calling startSync(). Cause: SDK versions 4.11 and earlier included an edge-case bug in the underlying mDNS (multicast DNS) library. Malformed mDNS packets broadcast by non-Ditto devices on the local network (for example, certain IoT devices or network appliances) could trigger an out-of-bounds array access in the mDNS parsing code, causing the SDK to panic. Fix:

Upgrade the SDK

Upgrade to Ditto SDK 4.12 or later (or SDK v5), which includes the fix for this mDNS parsing bug.

Investigate the network environment

If you cannot upgrade immediately, identify and isolate any devices on the local network that are broadcasting malformed mDNS packets. Recent additions of IoT devices, printers, or network appliances are common sources.

If your crash log contains a stack trace referencing mdns_sd with an index-out-of-bounds panic, upgrading the SDK is the recommended resolution. No application code changes are required.

Android App Store Submission Issues

Google Play Store 16KB Page Size Rejection

Starting in November 2025, Google Play requires all native libraries (.so files) in Android apps to be aligned to 16KB memory page sizes. If your app bundles an older version of the Ditto SDK, Google Play may reject your submission with an error similar to:

This release is not compliant with the Google Play 64-bit requirement or the 16 KB page size requirement.

This issue affects React Native apps using Ditto SDK versions earlier than 4.14.4. The libdittorn.so library in those versions is not 16KB-aligned.

Solution: Upgrade to one of the following SDK versions:

React Native SDK 4.14.4 or later (v4 line)
React Native SDK 5.0.0 or later (v5 line)

No code changes are required — upgrading the SDK version resolves the issue. After upgrading, rebuild and resubmit your app to Google Play.

Other Ditto SDK platforms (Kotlin, Swift, etc.) with Android targets may also require 16KB alignment. Check the release notes for your platform to confirm which version includes the fix.

Still stuck?

If you’re still stuck, please contact Ditto support.

Obtaining and Analyzing the Debug Logs

Synchronizing seems slow or comes to a halt over time

App is using too much memory, why?

Debugging Blocked Transactions

Causes of Blocked Transactions

Android App Store Submission Issues

Subscription Server Overload (503 Errors)

iOS mDNS Stale Record Crashes

Still stuck?

SDK crash: mDNS index out of bounds (4.11 and earlier)

​Obtaining and Analyzing the Debug Logs

​Setting the Logs to Debug Level

​Authentication

​Incorrect APP ID

​Outdated certificate

​Authentication server unavailable

​Ditto closing prematurely

​Common mistakes

​Is your AuthClient becoming garbage collected?

​Syncing With Big Peer

​Subscription Server Overload (503 Errors)

​Corrupted certificate

​Permissions and Subscriptions

​Permissions

​Subscriptions

​Query Parsing Errors

​Writes

​Did your device connect to the internet?

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

​Connection issues

Swift

Kotlin

JavaScript Web | Node.js | React Native

Bluetooth on Linux

​Bluetooth

​Apple Wireless Direct Link, P2P-Wifi, Wifi Aware

​Local Area Network (LAN)

​Debugging Blocked Transactions

​Did your certificate expire and fail to refresh?

​Verify that your webhook provider name is correctly copied in the Ditto portal

​Is your AuthClient becoming garbage collected?

​Bluetooth

​Apple Wireless Direct Link, P2P-Wifi, Wifi Aware

​Local Area Network (LAN)

​Slow Initial Sync from Ditto Server

​Symptoms

​Common Causes

​Resolution

​iOS mDNS Stale Record Accumulation

​Synchronization seems slow, or comes to a halt over time

​App is using too much memory, why?

​Debugging Blocked Transactions

​What is a “blocked” transaction?

​Read vs. Write Transactions

​Reading the Logs

​Originators

​Causes of Blocked Transactions

​User blocks User

​SDK crash: mDNS index out of bounds

​Android App Store Submission Issues

​Google Play Store 16KB Page Size Rejection

​Still stuck?

Obtaining and Analyzing the Debug Logs

Setting the Logs to Debug Level

Authentication

Incorrect APP ID

Outdated certificate

Authentication server unavailable

Ditto closing prematurely

Common mistakes

Is your AuthClient becoming garbage collected?

Syncing With Big Peer

Subscription Server Overload (503 Errors)

Corrupted certificate

Permissions and Subscriptions

Permissions

Subscriptions

Query Parsing Errors

Writes

Did your device connect to the internet?

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

Connection issues

Bluetooth

Apple Wireless Direct Link, P2P-Wifi, Wifi Aware

Local Area Network (LAN)

Debugging Blocked Transactions

Did your certificate expire and fail to refresh?

Verify that your webhook provider name is correctly copied in the Ditto portal

Is your AuthClient becoming garbage collected?

Bluetooth

Apple Wireless Direct Link, P2P-Wifi, Wifi Aware

Local Area Network (LAN)

Slow Initial Sync from Ditto Server

Symptoms

Common Causes

Resolution

iOS mDNS Stale Record Accumulation

Synchronization seems slow, or comes to a halt over time

App is using too much memory, why?

Debugging Blocked Transactions

What is a “blocked” transaction?

Read vs. Write Transactions

Reading the Logs

Originators

Causes of Blocked Transactions

User blocks User

SDK crash: mDNS index out of bounds

Android App Store Submission Issues

Google Play Store 16KB Page Size Rejection

Still stuck?