waitForFirstSync() blocks indefinitely when using manual sync stream subscription

[KarimTamani]

Hi PowerSync team

First of all, thank you for this amazing technology , PowerSync is exactly what we need and has been working great for us so far.
Recently, I started migrating from Sync Rules to Sync Streams. To do that, I:

Upgraded the PowerSync Service (Docker) to v1.18 (to support sync streams)
Upgraded the React client dependencies to:

"@powersync/react": "^1.8.2",
"@powersync/web": "^1.31.0"

After the upgrade, I created a simple test stream:

sync_rules:
  content: |
    streams:
      user_databases:
        query: select * from databases
        auto_subscribe: true
    config:
      edition: 2

I have a table called databases. Withauto_subscribe: true, the client connects automatically and fetches all data on the first connection. This works as expected , the initial data load completes successfully.

Issue with manual subscription (auto_subscribe: false)

When I set auto_subscribe: false on the stream, I want the client to fetch data only when I explicitly subscribe. For that, I use the following query in React:

const { data: databases, isLoading: loadingDatabases, isFetching: fetchingDatabases } = useQuery(
  toCompilableQuery(
    db.query.databases.findMany({
      orderBy: desc(databaseModel.createdAt),
      with: { user: true }
    })
  ),
  [],
  { streams: [{ name: "user_databases" }] }
);

Observed behavior:
No data is returned at all.

Attempting to set waitForStream: false:
{ streams: [{ name: "user_databases", waitForStream: false }] }

causes the query to remain in a perpetual loading state, and no data is fetched.

I also tried to handle the stream separately from the query, by subscribing manually:

const sub = await powerSync.syncStream('user_databases').subscribe();

// Resolve current status for the subscription
const status = powerSync.currentStatus.forStream(sub);
const progress = status?.progress;

// Wait for the subscription to complete its first sync
await sub.waitForFirstSync(); // <-- hangs indefinitely
console.log(status);

Result : waitForFirstSync() never resolves it blocks indefinitely.

My diagnosis is that the client never calls the PowerSync service for the stream. I’ve been watching the service logs in Docker: you can see the global connection established, but the user_databases stream never starts. When auto_subscribe is set to true, the stream shows up in the logs and works as expected.

Honestly, I’m out of options here. I don’t know what I’m missing , is there any version incompatibility? The waitForFirstSync() method seems to hang without raising an error, and I’m not sure why.

I would greatly appreciate any guidance on what I might be missing or the correct approach to handle manual stream subscriptions.

Thank you so much .

[stevensJourney]

Thanks for the detailed writeup. I think I have seen this issue before. Can you please confirm that you're using our Rust sync implementation? This is required in order to use sync stream subscriptions. The Rust implementation can be enabled when calling connect - an example is here.

 powerSync.connect(connector, { clientImplementation: SyncClientImplementation.RUST });

I can see how it's easy to miss this requirement. We're planning on making the Rust client the default at some point, which should prevent issues like this in future.

[KarimTamani]

Indeed, yes, @stevensJourney that turned out to be the issue. I was previously using a standard connection without a client implementation.

Once I specified the Rust client implementation, everything worked correctly and all data synced as expected.

I truly appreciate your help. Thanks a lot!