Trying better auth + Convex and Nextjs. There seems to be an issue with usePreloadedAuthQuery when c

[cursive girder]

Trying better auth + Convex and Nextjs. There seems to be an issue with usePreloadedAuthQuery when compared to usePreloadedQuery.

I fetch data in a server component using preloadAuthQuery and then use usePreloadedAuthQuery on the client component. During hydration, usePreloadedAuthQuery briefly returns undefined, causing a visible flash of empty content before data reappears. This doesn't happen with the standard usePreloadedQuery from convex/react — it hydrates synchronously with no flash.

My setup passes initialToken to ConvexBetterAuthProvider and all pages are auth-protected server-side via isAuthenticated(), so the client has a valid token from the first render. Is this expected behavior or a bug?

[tropic hare]

Hi @cursive girder. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

This looks like known, current behavior rather than something you’re doing wrong, but the knowledge sources don’t explicitly document usePreloadedAuthQuery’s exact hydration semantics, so I can’t say with certainty whether it’s considered a “bug” vs “known limitation” in the Better Auth integration.

What we do know from the docs and Discord threads:

• usePreloadedAuthQuery is specifically designed to “ensure server rendered data is rendered until authentication is ready.”[Migrate 0.10 – usePreloadedAuthQuery]
• With other auth providers (WorkOS, etc.), there is a general, known issue where preloaded data can “flash” or disappear briefly while the Convex client is waiting for auth to resolve on the client, even when the server-side preloaded query ran with a token.[How to use preload query with authentication; WorkOS + Convex race]
• The recommended workaround in those cases is to hold the preloaded result in client state and keep rendering it until client auth is ready (or to gate rendering behind an auth-loading state).[How to use preload query with authentication; WorkOS + Convex race]

In other words, the “flash” you’re seeing with usePreloadedAuthQuery matches the general pattern of preloaded data briefly disappearing while the client-side auth state catches up, which Convex staff have acknowledged as a shortcoming they’re working on improving.[How to use preload query with authentication]

Your specific situation (Better Auth, initialToken passed to ConvexBetterAuthProvider, and all pages already auth-protected server-side) should in principle avoid that race, but the sources don’t confirm that usePreloadedAuthQuery is fully optimized for that case. The docs only state its intent, not that it guarantees no flash in all setups.[Migrate 0.10 – usePreloadedAuthQuery]

Given the available information:

• It’s not clearly documented as expected behavior, but
• It matches a known class of issues around auth + preloaded queries,
• And the current recommended workaround is to keep rendering the preloaded result yourself until auth is ready (e.g. via local state), similar to the Better Auth example linked by Convex staff.[How to use preload query with authentication]

If you want to minimize the flash right now, the safest pattern (until the libraries improve) is:

"use client";

import { useState, useEffect } from "react";
import { useConvexAuth } from "convex/react";
import { usePreloadedAuthQuery } from "@convex-dev/better-auth/nextjs/client";
import type { Preloaded } from "convex/react";
import { api } from "@/convex/_generated/api";

export function MyComponent({
preloadedUserQuery,
}: {
preloadedUserQuery: Preloaded<typeof api.auth.getCurrentUser>;
}) {
const { isLoading } = useConvexAuth();
const freshUser = usePreloadedAuthQuery(preloadedUserQuery);
const [user, setUser] = useState(freshUser);

useEffect(() => {
if (!isLoading && freshUser !== undefined) {
setUser(freshUser);
}
}, [isLoading, freshUser]);

// Render user from local state so it doesn’t go undefined during hydration
if (!user) return null; // or a skeleton

return <div>{user.name}</div>;
}

That pattern is exactly what Convex staff have suggested for other auth integrations to avoid the hydration flash.[[How to use preload query with authentication](<https://discord.com/channels/1019350475847499849/1430407429505679462>)]

Since the sources don’t explicitly classify your `usePreloadedAuthQuery` behavior as a bug, the best next step is to treat it as a likely limitation and, if it’s blocking you, open an issue or share a minimal repro with the Convex team so they can confirm and potentially tighten the behavior in the Better Auth integration.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------