Debugging
Debugging Convex + Better Auth
Verbose logging
Backend
Turn on verbose logs in the component constructor. The component then logs the
configured baseURL and the request and response headers of each auth request.
export const authComponent = createClient(
components.betterAuth,
{
verbose: true,
}
);Anyone with access to your deployment logs can read verbose logs, so enable
them only while debugging. The component redacts credential headers
(Cookie, Authorization, Set-Cookie, Better-Auth-Cookie,
Set-Better-Auth-Cookie, Set-Auth-Token, Set-Auth-JWT, X-Api-Key) and
the query strings of Location and Referer; other headers are logged as
they are.
Database adapter
Better Auth's adapter debug logs show every database read and write the adapter
makes. Turn them on with debugLogs, which takes the same values as Better
Auth's adapter debugLogs option: true, or an object that turns on single
methods, such as { findOne: true }.
export const authComponent = createClient(
components.betterAuth,
{
debugLogs: true,
}
);Adapter debug logs print full database rows without redaction, including session tokens, password hashes, OAuth tokens and verification values such as password reset tokens and one-time codes. Enable them only while debugging.
Client side
Verbose logs in the client can be enabled on the Convex client constructor.
// Replace this with your framework prefixed environment variable
// for your project's Convex cloud URL
const convexUrl = import.meta.env.PUBLIC_CONVEX_URL as string;
const convex = new ConvexReactClient(convexUrl, {
verbose: true,
});Out of memory
If convex dev, convex deploy, or code push fails with an error like
JavaScript execution ran out of memory (maximum memory usage: 64 MB), try
these steps:
-
Use
registerRoutesLazy()instead ofregisterRoutes()inconvex/http.ts. This defers Better Auth initialization so it doesn't run during route registration. -
Import Better Auth plugins from their subpaths (e.g.,
better-auth/plugins/magic-linkinstead ofbetter-auth/plugins). Subpath imports pull in less code, reducing bundle size and memory usage.convex/auth.ts import { magicLink } from "better-auth/plugins/magic-link"; import { emailOTP } from "better-auth/plugins/email-otp"; -
Generate a debug bundle to see what's being included. The output contains an
isolatefolder (what runs in the Convex runtime) and anodefolder (what runs in Node.js). Check theisolatebundle forconvex/http.tsto see if unexpected dependencies are inflating it.npx convex dev --once --debug-bundle-path /tmp/convex-bundle