Skip to main content

​
Common Issues

Tip: Asking the AI bot on this page, or on the #gpt-help channel on our Discord server, is a good way to troubleshoot common issues.

​
SqliteException: Could not load extension or similar

This client-side error or similar typically occurs when PowerSync is used in conjunction with either another SQLite library or the standard system SQLite library. PowerSync is generally not compatible with multiple SQLite sources. If another SQLite library exists in your project dependencies, remove it if it is not required. In some cases, there might be other workarounds. For example, in Flutter projects, we’ve seen this issue with sqflite 2.2.6, but sqflite 2.3.3+1 does not throw the same exception.

​
PSYNC_S2305: Too many buckets / Parameter query results

PowerSync groups the data each user syncs into internal partitions called buckets. Each user has a limit on how many they can sync. When a user exceeds it, their sync fails with a PSYNC_S2305 error in your Sync & API logs. This error is caused by one of two limits, both with a default of 1,000:
  • Buckets per connection: the unique buckets a user syncs. The message reads Too many buckets: N (limit of M).
  • Parameter query results: the rows your parameter lookups return, counted before duplicates are removed. The message reads Too many parameter query results (limit of N).
Read the message to see which limit you reached, since the fix is different for each. Your logs also show where the count comes from:
  • The same PSYNC_S2305 log entry includes a breakdown of the streams contributing the most. For a parameter-limit error, the last stream listed is the one that ran when the limit was reached. That stream is not always the cause, so check every stream in the breakdown.
  • Checkpoint logs record buckets and param_results for each connection, so you can see how close a user is to either limit. Find them in your instance logs.
To further diagnose and resolve this error, see Reducing Bucket Count. For how buckets are generated and counted in the first place, see Bucket Count.

​
Tools

Troubleshooting techniques depend on the type of issue:
  1. Connection issues between client and server: See the tools below.
  2. Expected data not appearing on device: See the tools below.
  3. Data lagging behind on PowerSync Service: Data on the PowerSync Service instance cannot currently directly be inspected. This is something we are investigating.
  4. Writes to the backend source database are failing: PowerSync is not actively involved: use normal debugging techniques (server-side logging; client and server-side error tracking).
  5. Updates are slow to sync, or queries run slow: See Performance

​
Sync Diagnostics Client

Access the Sync Diagnostics Client here: https://diagnostics-app.powersync.com This is a standalone web app that presents data from the perspective of a specific user. It can be used to:
  • See stats about the user’s local database.
  • Inspect tables, rows and buckets on the device.
  • Query the local SQL database.
  • Identify common issues, e.g. too many buckets.
See the Readme for further details.

​
Instance Logs

See Monitoring and Alerting.

​
SyncStatus API

We also provide diagnostics via the SyncStatus APIs in the client SDKs. Examples include the connection status, last completed sync time, and local upload queue size. If for example, a change appears to be missing on the client, you can check if the last completed sync time is greater than the time the change occurred. For usage details, refer to the respective client SDK docs. The JavaScript SDKs (React Native, web) also log the contents of bucket changes to console.debug if verbose logging is enabled. This should log which PUT/PATCH/DELETE operations have been applied from the server.

​
Inspect Local SQLite Database

Opening the SQLite file directly is useful for verifying sync state, inspecting raw table contents, and diagnosing unexpected data. See Understanding the SQLite Database for platform-specific instructions (Android, iOS, Web), how to merge the WAL file, and how to analyze storage usage. Our Sync Diagnostics Client and several of our demo apps also contain a SQL console view to inspect the local database contents without pulling the file. Consider implementing similar functionality in your app. See a React example here.

​
Client-Side Logging

Our client SDKs support logging to troubleshoot issues. Here’s how to enable logging in each SDK:
  • JavaScript-based SDKs (Web, React Native, and Node.js) - Implement the PowerSyncLogger interface, or use createConsoleLogger(). For example: const logger = createConsoleLogger({ minLevel: LogLevels.debug }). Pass the logger to PowerSyncDatabase via the logger option. For the Web SDK, you can also enable the debugMode flag to log SQL queries on Chrome’s Performance timeline.
  • Dart/Flutter SDK - Logging is enabled by default since version 1.1.2 and outputs logs to the console in debug mode.
  • Kotlin SDK - Uses Kermit Logger. By default shows Warnings in release and Verbose in debug mode.
  • Swift SDK - Supports configurable logging with DefaultLogger and custom loggers implementing LoggerProtocol. Supports severity levels: .debug, .info, .warn, and .error.
  • .NET SDK - Uses .NET’s ILogger interface. Configure with LoggerFactory to enable console logging and set minimum log level.

​
Performance

When running into issues with data sync performance, first review our expected Performance and Limits. These are some common pointers when it comes to diagnosing and understanding performance issues:
  1. You will notice differences in performance based on the row size (think 100 byte rows vs 8KB rows)
  2. The initial sync on a client can take a while in cases where the operations history is large. See Compacting Buckets to optimize sync performance.
  3. You can get big performance gains by using transactions & batching as explained in this blog post.
Struggling with client-side performance issues? This page describes tools to diagnose performance of the PowerSync Service. Optimizing client-side query performance is described in SQLite Performance Optimization.

​
Diagnosing Sync Latency

If writes are slow to reach the client, there is no single trace that covers the full path. Isolate each stage of the pipeline to find the bottleneck. The downstream pipeline (source database to client) has two stages:
  1. Source database to PowerSync Service (replication).
  2. PowerSync Service to client (sync session).
The upstream path (the client sending a write to your backend, your backend processing it, and your backend committing to the source database) sits outside PowerSync and is not covered by the diagnostics below. To measure that, instrument your backend API directly.

​
Measuring Downstream Latency (Source to Device)

To measure the downstream pipeline, put a timestamp in the data itself. When a row is written or updated in your source database, set a column to the current server time (e.g. updated_at = NOW()). On the client, compare that timestamp to the time the row arrives in the local database. The difference is the time from the source write being committed to the row being visible on the device. This gives you a single number for the downstream pipeline but does not tell you which stage is slow. Use the per-stage diagnostics below to break it down.

​
Stage 1: Source Database to PowerSync Service

Check the Replication Lag chart in the Metrics view of the PowerSync Dashboard. This shows whether replication from your source database is keeping up. Replicator logs in the Logs view surface any replication errors that would cause delays at this stage. For a deeper walkthrough of what drives replication lag, how to interpret it for your specific source (Postgres, MongoDB, MySQL, SQL Server), and how to reduce it, see Replication Lag.

​
Stage 2: PowerSync Service to Client

Sync & API logs in the PowerSync Dashboard record a Sync stream started event when a client connects and a Sync stream complete event when the session ends. The complete event includes how many operations were synced, how much data was transferred, and how long the connection stayed open. See Correlating Sync Sessions for the full list of fields on each event. Custom metadata attached at connect() time is included in both events, so you can also filter by app version, environment, or other context you set.

​
Common Causes of Latency

  • Large initial sync: if your Sync Streams/Rules result in a large dataset, the first sync after connecting will be slow. Inspect bucket sizes and sync state with the Sync Diagnostics Client.
  • Upload queue blocking downloads: by default, uploads are processed before downloads, so a backlogged upload queue delays receiving new data. Buckets and streams at priority 0 are not blocked by uploads, but come with the trade-off of potential sync inconsistencies.
  • Replication lag on the source database: high write volume, long-running transactions, bulk updates, or backfills can cause replication to fall behind faster than the service can drain it. See Replication Lag for source-specific causes and fixes.
  • Too many buckets per user: incremental sync overhead scales roughly linearly with the number of buckets per user. See Too Many Buckets above.