Troubleshooting

​

Common issues

​

SqliteException: Could not load extension or similar

​

RangeError: Maximum call stack size exceeded on iOS or Safari

1. Use OPFSCoopSyncVFS (Recommended): Switch to the OPFSCoopSyncVFS virtual file system, which provides better Safari compatibility and multi-tab support:

import { PowerSyncDatabase, WASQLiteOpenFactory, WASQLiteVFS } from '@powersync/web';

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: new WASQLiteOpenFactory({
    dbFilename: 'exampleVFS.db',
    vfs: WASQLiteVFS.OPFSCoopSyncVFS,
    flags: {
      enableMultiTabs: typeof SharedWorker !== 'undefined'
    }
  }),
  flags: {
    enableMultiTabs: typeof SharedWorker !== 'undefined'
  }
});

2. Disable Web Workers (Alternative): Set the useWebWorker flag to false, but note that this disables multi-tab support:

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'powersync.db'
  },
  flags: {
    useWebWorker: false
  }
});

​

Too Many Buckets (PSYNC_S2305)

​

How buckets are created in Sync Streams

regions
|_ orgs                  
   |_ projects           
   |  |_ tasks           
   |  |_ project_assets  (project_assets.project_id → projects.id)
   |     ↔ assets        (project_assets.asset_id → assets.id)
   |_ org_membership     (org_membership.org_id → orgs.id)
      ↔ users            (org_membership.user_id → users.id)

streams:
  org_projects_tasks:
    auto_subscribe: true
    with:
      user_orgs:     SELECT org_id FROM org_membership WHERE user_id = auth.user_id()
      user_projects: SELECT id FROM projects WHERE org_id IN (SELECT org_id FROM org_membership WHERE user_id = auth.user_id())
    queries:
      - SELECT * FROM orgs     WHERE id           IN user_orgs     # keyed by org
      - SELECT * FROM projects WHERE id           IN user_projects  # keyed by project
      - SELECT * FROM tasks    WHERE project_id   IN user_projects  # keyed by project

user_orgs     → [org-A, org-B]                                     (2 values)
user_projects → [proj-1, proj-2, proj-3, proj-4, proj-5, proj-6]   (6 values)

​

Diagnosing which streams are contributing

• The PSYNC_S2305 error log includes a breakdown showing which stream definitions are contributing the most bucket instances (top 10 by count).
• PowerSync Service checkpoint logs record the total parameter result count per connection. You can find these in your instance logs. For example:
  New checkpoint: 800178 | write: null | buckets: 7 | param_results: 6 ["5#user_data|0[\"ef718ff3...\"]","5#user_data|1[\"1ddeddba...\"]","5#user_data|1[\"2ece823f...\"]", ...]
  
  • buckets — total number of active buckets for this connection
  • param_results — the total parameter result count across all stream definitions for this connection
  • The array lists the active bucket names and the value in [...] is the evaluated parameter for that bucket
• The Sync Diagnostics Client lets you inspect the buckets for a specific user, but note that it will not load for users who have exceeded the bucket limit since their sync connection fails before data can be retrieved. Use the instance logs and error breakdown to diagnose those cases.

​

Reducing bucket count in Sync Streams

streams:
  user_settings:
    query: SELECT * FROM settings WHERE user_id = auth.user_id()
  user_prefs:
    query: SELECT * FROM preferences WHERE user_id = auth.user_id()
  user_org_list:
    query: SELECT * FROM org_membership WHERE user_id = auth.user_id()
  user_region:
    query: SELECT * FROM region_members WHERE user_id = auth.user_id()
  user_profile:
    query: SELECT * FROM profiles WHERE user_id = auth.user_id()

streams:
  user_data:
    queries:
      - SELECT * FROM settings WHERE user_id = auth.user_id()
      - SELECT * FROM preferences WHERE user_id = auth.user_id()
      - SELECT * FROM org_membership WHERE user_id = auth.user_id()
      - SELECT * FROM region_members WHERE user_id = auth.user_id()
      - SELECT * FROM profiles WHERE user_id = auth.user_id()

streams:
  org_data:
    query: SELECT * FROM orgs WHERE id IN (SELECT org_id FROM org_membership WHERE user_id = auth.user_id())

streams:
  my_org_memberships:
    query: SELECT * FROM org_membership WHERE user_id = auth.user_id()

streams:
  org_projects_tasks:
    with:
      user_orgs: SELECT org_id FROM org_membership WHERE user_id = auth.user_id()
      user_projects: SELECT id FROM projects WHERE org_id IN (SELECT org_id FROM org_membership WHERE user_id = auth.user_id())
    queries:
      - SELECT * FROM orgs WHERE id IN user_orgs
      - SELECT * FROM projects WHERE id IN user_projects
      - SELECT * FROM tasks WHERE project_id IN user_projects

streams:
  org_projects_tasks:
    with:
      user_orgs: SELECT org_id FROM org_membership WHERE user_id = auth.user_id()
    queries:
      - SELECT * FROM orgs WHERE id IN user_orgs
      - SELECT * FROM projects WHERE org_id IN user_orgs
      - SELECT * FROM tasks WHERE org_id IN user_orgs

streams:
  assets_in_projects:
    with:
      user_projects: SELECT id FROM projects WHERE org_id IN (SELECT org_id FROM org_membership WHERE user_id = auth.user_id())
    query: |
      SELECT assets.* FROM assets
      JOIN project_assets ON project_assets.asset_id = assets.id
      WHERE project_assets.project_id IN user_projects

streams:
  assets_in_projects:
    with:
      user_projects: SELECT id FROM projects WHERE org_id IN (SELECT org_id FROM org_membership WHERE user_id = auth.user_id())
    query: |
      SELECT assets.* FROM assets
      INNER JOIN json_each(assets.project_ids) AS p
      INNER JOIN user_projects ON p.value = user_projects.id

streams:
  project_tasks:
    with:
      user_projects: SELECT id FROM projects WHERE org_id IN (SELECT org_id FROM org_membership WHERE user_id = auth.user_id())
    query: SELECT * FROM tasks WHERE project_id IN user_projects

streams:
  project_tasks:
    with:
      user_projects: SELECT id FROM projects WHERE org_id IN (SELECT org_id FROM org_membership WHERE user_id = auth.user_id())
    query: SELECT * FROM tasks WHERE project_id = subscription.parameter('project_id') AND project_id IN user_projects

​

Increasing the limit

​

Tools

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

• 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.

​

Instance Logs

​

SyncStatus API

​

Inspect local SQLite Database

​

Client-side Logging

• JavaScript-based SDKs (Web, React Native, and Node.js) - You can use our built-in logger based on js-logger for logging. Create the base logger with const logger = createBaseLogger() and enable with logger.useDefaults() and set level with logger.setLevel(LogLevel.DEBUG). 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

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 optimizes sync performance.
3. You can get big performance gains by using transactions & batching as explained in this blog post.

​

Web: Logging queries on the performance timeline

• PowerSync queries from client code.
• Internal statements from PowerSync, including queries saving sync data, and begin/commit statements.

• The time waiting for the global transaction lock, but includes all overhead in worker communication. This means you won’t see concurrent queries in most cases.
• Internal statements from powersync-sqlite-core.

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: {
    dbFilename: 'powersync.db',
    debugMode: true // Defaults to false. To enable in development builds, use
      // debugMode: process.env.NODE_ENV !== 'production'
  }
});