Troubleshooting
Diagnose setup, SSR, authentication, realtime, and upload failures from the boundary inward.
Start with the first boundary that fails. Avoid changing several options at once; that hides the cause.
Nuxt does not start after installation
Symptom: nuxt prepare or nuxt dev fails with ERR_PNPM_IGNORED_BUILDS.
pnpm 10 and newer block build scripts. Run pnpm approve-builds (pnpm 10.1 and newer), allow esbuild, and start Nuxt again.
Module cannot find Convex
Symptom: the build or the browser console reports No Convex deployment URL is configured, Convex composables fail with plugin is not installed, or queries never connect.
- Confirm
NUXT_PUBLIC_CONVEX_URLexists in the environment running Nuxt. - Confirm it points to the intended
.convex.clouddeployment. - Restart Nuxt after changing local environment files.
- If the value was added only after a production build, use Nuxt's
NUXT_PUBLIC_*runtime override or rebuild.
If the URL is set and composables still fail with plugin is not installed, check two causes:
- With
client.connect: 'on-demand', a component used a Convex composable beforeuseConvexActivation().activate()finished. Mount such components only after activation. See on-demand client. - The page loaded two copies of
@lupinum/better-convex-vue, and each copy has its own plugin. Check that only one version is installed withpnpm why @lupinum/better-convex-vue. The Nuxt module keeps the package out of Vite's pre-bundling, so do not add it tovite.optimizeDeps.include.
SSR succeeds but hydration changes the page
Symptom: initial HTML and the hydrated client show different identity or query data.
- Do not read browser-only state during server rendering.
- Pass query arguments that are the same on the server and in the browser.
- Keep the same query auth mode on server and client.
- Use
useConvexQueryinstead of manually combining a server fetch and a separate client subscription. - Check the structured query
statusanderrorinstead of treating empty data as loading.
Auth proxy fails
Symptom: sign-in returns a proxy or token-exchange error.
Check, in order:
convex.siteUrlorNUXT_PUBLIC_CONVEX_SITE_URLtargets the correct HTTP Actions origin.- Better Auth routes are registered in
convex/http.ts. - Convex has
SITE_URLset to the exact Nuxt origin. - Convex has versioned
BETTER_AUTH_SECRETS, and its deployment-owned built-inCONVEX_SITE_URLmatches the selected deployment. - Nuxt and Convex share the same private
BCN_AUTH_PROXY_IP_SECRET. - The deployment preserves the
/api/auth/*Nitro route. - No proxy or CDN rewrites the host, cookies, request bytes, or redirect behavior unexpectedly.
Auth fails with a trusted client IP header error
Symptom: the build fails with auth.trustedClientIpHeader is required outside exact loopback development origins, or every auth request fails with code BCN_AUTH_PROXY_CLIENT_IP_INVALID (400) or BCN_AUTH_PROXY_IP_SECRET_INVALID (500).
- Set
BCN_AUTH_TRUSTED_CLIENT_IP_HEADERfor the build as well as the runtime.nuxt.config.tsreads it during the build. - Check that the header exists on real requests and contains one IP address, not a list. On Vercel, use
x-real-ip; see Deploy to Vercel. BCN_AUTH_PROXY_IP_SECRET_INVALIDmeans the Nuxt server has noBCN_AUTH_PROXY_IP_SECRET, or it is shorter than 32 bytes. Set the same value that Convex has.- Repeated
429responses mean that many users share the same reported IP. Pick a header that contains the client IP, not the address of a proxy.
Social sign-in returns account_not_linked
A user with the same email address already exists. The library never joins accounts automatically. The user signs in with the existing method and links the provider with client.linkSocial(). See Social sign-in.
A protected query runs anonymously
auth: 'optional' waits until the auth state is known but permits anonymous execution. Use auth: 'required' when the call must not run without identity, and still enforce identity inside the Convex handler.
Use auth: 'none' only for intentionally public data. It always uses the dedicated anonymous transport, even while the user is signed in.
Realtime stops updating
- Inspect connection state.
- Check that CSP and the network permit the exact Convex WebSocket origin.
- Confirm that a mounted component still uses the query. The subscription stops when the last component that uses it unmounts.
- Do not construct a separate raw
ConvexClientfor the same state.
Errors lose useful detail
Use ConvexCallError fields—kind, code, status, data, and functionName—rather than parsing message strings. functionName names the Convex function that failed. Run unknown failures, including $fetch errors from Nitro routes, through normalizeConvexError. The library intentionally does not expose raw upstream bodies or serialize cause.
A server error shows Convex application error when its ConvexError data has no string message. Throw new ConvexError({ code, message }) or new ConvexError('Readable text') to give the user a specific message.
A call fails with CLIENT_UNAVAILABLE
The browser Convex client does not exist yet. This happens during server rendering, in a build without a Convex URL, or before the browser runtime starts.
- Call
mutate,run,upload,useConvex()methods, anduseConvexAuth().clientmethods from event handlers oronMounted(), not during setup. - Use
useConvexQueryfor server-rendered data andserverConvex(event)in Nitro handlers. - Confirm
NUXT_PUBLIC_CONVEX_URLis set for the environment.
An SSR query times out or returns too much data
An SSR query or serverConvex call fails with a transport error when it runs longer than convex.server.queryTimeoutMs or returns more than convex.server.maxResponseBytes. Narrow or paginate the query first. Raise the server limits only for a measured need.
Uploads stall
Check file limits before requesting an upload URL, confirm the generated URL has not expired, and inspect the active upload's progress and error state. For an application-owned multi-file workflow, also inspect its worker scheduling and per-item state. A successful storage upload does not automatically create an application record; treat those as two explicit steps and define compensation for the second step failing.
For a minimal reproduction, disable auth only if the failure is unrelated to identity, reduce the page to one explicit query or call, and record the public structured error. Never attach session cookies, bearer tokens, or secrets to an issue.