Convex + Better Auth

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.

convex/auth.ts
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 }.

convex/auth.ts
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.

src/main.ts
// 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 of registerRoutes() in convex/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-link instead of better-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 isolate folder (what runs in the Convex runtime) and a node folder (what runs in Node.js). Check the isolate bundle for convex/http.ts to see if unexpected dependencies are inflating it.

    npx convex dev --once --debug-bundle-path /tmp/convex-bundle

On this page