Bug: beforeLoad* hook throws before prefetchInfiniteQuery runs

[olliethedev]

Bug: 500 error when beforeLoad* hook throws before prefetchInfiniteQuery runs (empty query cache causes fresh SSR fetch)

Problem

When a consumer's beforeLoad* hook (e.g. beforeLoadPosts) throws an error — instead of letting the request reach the API — the plugin's createPostsLoader catch block fires before prefetchInfiniteQuery has run. The query cache is left empty for that key.

On the next step, React 18 streaming SSR renders the component tree. useSuspenseInfiniteQuery finds no cached data/error and initiates a fresh SSR fetch. This fresh fetch returns a 403/401 from the backend. In streaming SSR, errors thrown during a subsequent Suspense boundary resolution can escape client-side ErrorBoundaries and bubble up to Next.js as an unhandled error, producing a 500 Internal Server Error page instead of a graceful error UI.

Root cause

In createPostsLoader (and the equivalent loaders in other plugins) the query key variables are constructed inside the try block, after the hook invocation:

try {
  if (hooks?.beforeLoadPosts) {
    await runClientHookWithShim(...)   // ← throws here
  }

  const client = createApiClient(...)
  const queries = createBlogQueryKeys(...)
  const listQuery = queries.posts.list(...)  // never reached

  await queryClient.prefetchInfiniteQuery({ ...listQuery, initialPageParam: 0 })
  // ↑ also never reached — cache stays empty
} catch (error) {
  if (isConnectionError(error)) { ... }
  if (hooks?.onLoadError) {
    await hooks.onLoadError(error as Error, context)
  }
  // cache still empty — component will trigger a fresh SSR fetch
}

Because listQuery is never built, the catch block cannot write anything to the cache. useSuspenseInfiniteQuery then suspends and triggers a network request during streaming, which returns an error that bypasses the ErrorBoundary.

Expected behaviour

If a beforeLoad* hook throws, the error should be stored in the query cache under the same query key the component will use. useSuspenseInfiniteQuery then finds the cached error, throws it synchronously, and the ComposedRoute ErrorBoundary renders its fallback UI — no fresh network request, no 500.

Reproduction

Configure a beforeLoadPosts hook that throws for unauthenticated users:

blogClientPlugin({
  hooks: {
    beforeLoadPosts: async (filter, context) => {
      if (!filter.published) {
        const session = await getSession(context);
        if (!session) throw new Error("Unauthorized to view drafts");
      }
    },
    onLoadError(error) {
      redirect("/p/auth/sign-in"); // or display an error
    },
  },
})

Then navigate to /blog/drafts without a session. Expected: redirect or error UI. Actual: 500.

Proposed fix

Move the query key construction outside the try block (before the hook call) so it is always available in the catch block. When a non-connection error is caught, write it into the cache:

// Build query references before the try so catch can always populate the cache
const client = createApiClient<BlogApiRouter>({ baseURL: apiBaseURL, basePath: apiBasePath });
const queries = createBlogQueryKeys(client, headers);
const listQuery = queries.posts.list({ query: undefined, limit, published });

try {
  if (hooks?.beforeLoadPosts) {
    await runClientHookWithShim(...)
  }
  await queryClient.prefetchInfiniteQuery({ ...listQuery, initialPageParam: 0 })
  // ...
} catch (error) {
  if (isConnectionError(error)) {
    console.warn("[btst/blog] ...")
  } else {
    // Seed the cache with the error so useSuspenseInfiniteQuery throws it
    // to the ErrorBoundary instead of triggering a fresh (failing) SSR fetch.
    const errToStore = error instanceof Error ? error : new Error(String(error));
    await queryClient.prefetchInfiniteQuery({
      queryKey: listQuery.queryKey,
      queryFn: () => { throw errToStore; },
      initialPageParam: 0,
    });
  }
  if (hooks?.onLoadError) {
    await hooks.onLoadError(error as Error, context);
  }
}

The same pattern applies to the equivalent loaders in the CMS, Form Builder, and any other plugin that uses prefetchInfiniteQuery with a beforeLoad* hook.

Note on existing e2e tests

The existing smoke.auth-blog.spec.ts browser tests pass because they exercise a different code path: the hook in the example apps does not throw — it returns false / allows the request through, and the API itself returns 403. React Query's prefetchInfiniteQuery stores that 403 response as an error in the cache, so useSuspenseInfiniteQuery finds a cached error and the ErrorBoundary renders correctly.

The failing path (hook throws before the prefetch) is not currently covered by any browser-level e2e test. A test that configures beforeLoadPosts to throw and verifies the page shows an error state (not a 500) would prevent regressions.

[olliethedev]

Additional reproduction context

This issue has a related but distinct manifestation worth documenting.

Symptom

/p/blog/new showed the new-post editor to unauthenticated users instead of redirecting to sign-in. The edit route (/p/blog/:slug/edit) worked correctly.

Root cause (two-layer problem)

Layer 1 — Wrong Next.js route captured the URL (consumer app bug)

A common pattern in Next.js apps using the blog plugin is to create app/p/blog/[slug]/page.tsx — a static ISR page (revalidate = 3600) for SSG blog posts. Because a dynamic segment [slug] is more specific than a catch-all [[...all]], Next.js routes /p/blog/new to [slug] (with slug = "new") instead of the catch-all.

The [slug] SSG page typically:

• Passes session: null explicitly (no auth context needed for public posts)
• Calls myStack.api.blog.prefetchForRoute() (the SSG helper) — not route.loader()
• The yar router matches /blog/new as the newPost static route (static routes take priority over /blog/:slug)
• Renders NewPostPageComponent directly — no auth hook ever fires
• Response is cached via ISR, so subsequent requests serve the cached unauthenticated shell

Why /blog/:slug/edit still worked: The edit URL has an extra segment, so [slug] never captures it — it goes through the catch-all which does call route.loader() and triggers afterLoadPost → onLoadError → redirect().

Layer 2 — Even if the correct route is hit, redirect() from onLoadError may not propagate reliably

This connects directly to the issue as filed. When beforeLoadNewPost throws before any prefetchQuery runs:

• The query cache is empty for the new-post route (there's nothing to prefetch for a create form)
• onLoadError → redirect() is called and throws NEXT_REDIRECT
• Empirically, NEXT_REDIRECT from inside the loader's catch block does not reliably propagate out of route.loader() in this case
• The checkAuthErrors() fallback in the consumer's page.tsx finds nothing in the cache — so it doesn't redirect either

The edit route avoids this because prefetchQuery runs first (real async I/O), and the afterLoadPost hook fires after the fetch, by which point the async context is fully established and NEXT_REDIRECT propagates correctly.

Fix for the consumer app

1. Create app/p/blog/new/page.tsx — a static segment beats a dynamic one, so Next.js routes /p/blog/new to this dedicated page instead of [slug]. The page delegates to the catch-all which has full session + auth-hook support.

2. Guard app/p/blog/[slug]/page.tsx with if (route.routeKey !== "post") notFound() to prevent any reserved slug (e.g. drafts) from accidentally rendering admin UI via the ISR cache.

Suggested fix for the @btst/stack package (issue #89)

The proposed fix in the issue description (moving query-key construction outside the try block and seeding the cache with the error in the catch block) would address Layer 2 above. The empty-cache case currently leaves checkAuthErrors() blind for routes with no data to prefetch.

For the beforeLoadNewPost case specifically, the fix would look like:

// Build query refs BEFORE the try so the catch block can always populate the cache
const client = createApiClient<BlogApiRouter>({ baseURL: apiBaseURL, basePath: apiBasePath });
const queries = createBlogQueryKeys(client, headers);
const newPostQuery = queries.posts.newPost();  // sentinel key for the new-post route

try {
  if (hooks?.beforeLoadNewPost) {
    await runClientHookWithShim(() => hooks.beforeLoadNewPost!(context), "...");
  }
} catch (error) {
  if (!isConnectionError(error)) {
    const errToStore = error instanceof Error ? error : new Error(String(error));
    // Seed the cache so useSuspenseQuery / checkAuthErrors() can find the error
    await queryClient.prefetchQuery({
      queryKey: newPostQuery.queryKey,
      queryFn: () => { throw errToStore; },
      retry: false,
    });
  }
  if (hooks?.onLoadError) {
    await hooks.onLoadError(error as Error, context);
  }
}

This ensures that even when onLoadError → redirect() doesn't propagate (due to the timing/context issue described in Layer 2), the error is in the cache for the checkAuthErrors() fallback to catch.