Skip to content

Handle failed paginated queries without throwing or resetting forever - #65

Merged
mmailaender merged 2 commits into
mainfrom
fix/paginated-query-errors
Oct 14, 2026
Merged

mmailaender merged 2 commits into
mainfrom
fix/paginated-query-errors

Conversation

@mmailaender

@mmailaender mmailaender commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #61. Thanks @stickerdaniel for the detailed report and the suggested fix, which this follows.

Summary

  • Failed paginated queries no longer throw during setup. Errors the Convex client throws reach error, and the subscription is always cleaned up.
  • InvalidCursor resets once, then shows the error, instead of resetting forever.
  • convexLoadPaginated recovers from InvalidCursor. It used to stay in LoadingFirstPage; it now resubscribes.
  • One shared subscription helper for usePaginatedQuery and the detached paginated query (convexLoadPaginated, createDetachedPaginatedQuery) replaces two copies of the same code.
  • Verified: 219 unit tests, svelte-check, lint, e2e (42 passed). The new tests fail against main.
  • Known limit, needs onPaginatedUpdate_experimental: a failed page never reaches onError, and later transitions throw (1.46.0) convex-js#193: when subscribing itself throws, the Convex client has already registered the subscription and returns no handle to release it. This PR surfaces the error and never retries in that case, so it adds no further registrations, but it can't release the one the client leaked.

Why

The issue describes two production bugs in usePaginatedQuery:

  1. The Convex client throws instead of calling onError. It throws from getCurrentValue() once a page has failed, and from onPaginatedUpdate_experimental() when another subscriber already holds the query in a failed state (onPaginatedUpdate_experimental: a failed page never reaches onError, and later transitions throw (1.46.0) convex-js#193). The hook didn't catch either, so the $effect threw before returning its cleanup. The subscription leaked and error was never set.
  2. InvalidCursor reset without a limit. If another subscriber keeps the failed query alive, every resubscription gets the same InvalidCursor. The hook stayed in LoadingFirstPage forever.

The detached paginated query behind convexLoadPaginated had the same gaps, plus two more:

  • It never resubscribed after the state machine reset on InvalidCursor, so it stayed in LoadingFirstPage.
  • It rejected the load on the first InvalidCursor, even though the reset handled it.

Both copies also read getCurrentValue() through a const inside the update callback. A callback the client runs synchronously while subscribing would hit the TDZ.

What

  • shared/paginated_subscription.ts (new): subscribePaginated().
    • Catches errors from onPaginatedUpdate_experimental() and getCurrentValue() and passes them to onError, with a retryable flag.
    • An error thrown by onPaginatedUpdate_experimental() itself is not retryable. Convex 1.41's onPaginatedUpdate_experimental registers the subscription (paginatedClient.subscribe, then listeners.add) before the cached-value lookup that throws. It shares one paginated query per args, so a retry would fail the same way and leave another registration behind.
    • Always returns a cleanup.
    • Reads a snapshot delivered synchronously while subscribing exactly once.
    • Skips reading after a synchronous error.
  • PaginatedQueryStateMachine:
    • onError resets on InvalidCursor only once, then surfaces it as the error.
    • onError(error, { allowReset: false }) surfaces even an InvalidCursor without resetting; the callers use this for non-retryable errors.
    • The reset is re-armed by a real page (status !== 'LoadingFirstPage'), changed args, or reset().
    • The empty loading snapshot right after a resubscribe deliberately doesn't re-arm it; otherwise the loop from the issue would continue.
  • usePaginatedQuery: uses the helper. The effect always returns its cleanup.
  • Detached paginated query: uses the helper. After a handled InvalidCursor it restarts the subscription (in a microtask, with a new generation so old loadMore callbacks stay inert). A load waiting for its first page keeps waiting; a second InvalidCursor rejects it with the error.

How

  • Tests:
    • paginated_subscription.spec.ts: thrown errors from both client calls (with the retryable flag), a cleanup that is always returned, synchronous snapshot and error ordering.
    • paginated_query_state.spec.ts: one reset, the error on a repeat, no reset with allowReset: false, and the three re-arm paths.
    • query-detached.spec.ts: resubscribe once after InvalidCursor while the load keeps waiting, the error when it persists, no retry when subscribing throws, and a failed page thrown by getCurrentValue().
  • Not covered by a test: usePaginatedQuery itself has no mounted test, since the repo has no DOM test setup. Its subscription logic is now the tested helper, and the hook only wires it to the state machine.
  • convex-js#193: this fix works with the current Convex client by catching what it throws. Once the client reports these errors through onError and releases its registration on failure, they arrive as retryable errors, and no subscription leaks.

Fixes #61.

- New shared subscribePaginated() used by usePaginatedQuery and the
  detached paginated query (convexLoadPaginated): errors the Convex client
  throws from getCurrentValue() or onPaginatedUpdate_experimental() (see
  convex/convex-js#193) go to onError, a cleanup is always returned,
  and a synchronous first callback no longer hits the TDZ.
- PaginatedQueryStateMachine resets once on InvalidCursor; a repeated one
  before a page arrived is surfaced as the error. A loaded page, changed
  args or reset() re-arm the reset.
- The detached paginated query resubscribes after an InvalidCursor reset
  instead of staying in LoadingFirstPage.
@vercel

vercel Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
convex-svelte Ready Ready Preview Oct 13, 2026 8:23am UTC

Request Review

onPaginatedUpdate_experimental() registers the subscription before the
cached-value lookup that throws for a failed page, and returns no handle
to release it (convex/convex-js#193). The client shares one paginated
query per args, so resubscribing after such an error fails the same way
and leaves another registration behind. Report these errors as not
retryable: the state machine surfaces them (also an InvalidCursor)
instead of resetting, so usePaginatedQuery and the detached query don't
resubscribe.

@mikecann mikecann left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Micha, looks good, and thanks for the really thorough write up on the convex/convex-js#193 limit, made it much easier to follow.

@pkg-pr-new

pkg-pr-new Bot commented Oct 14, 2026

Copy link
Copy Markdown

commit: 3e72089

@mmailaender
mmailaender merged commit df4f721 into main Oct 14, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — 556756bc Deployed Oct 13, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

usePaginatedQuery: failed queries throw during setup and InvalidCursor resets loop

2 participants