Debugging

Clearing state

If you're seeing unexpected behavior, the first thing to try clearing local storage, cookies (if using Next.js), and secure storage (if using React Native), or running in an incognito window which does not have the same cookies or local storage, and seeing if the issue persists.

The relevant keys are prefixed with __convexAuth (or __Host-convexAuth for Next.js).

Enabling verbose logging

Having more logs can help you spot potential issues, and understand what's going. They're also very helpful to include when asking for help or filing issues.

Client

You can enable verbose logging on the client when you instantiate the ConvexReactClient

const client = new ConvexReactClient(process.env.CONVEX_URL, {
  verbose: true,
});

Logs will appear in the browser console when you run your app.

Convex functions

You can enable verbose logging in your Convex functions by setting the AUTH_LOG_LEVEL to DEBUG in the Convex dashboard or via the command line:

npx convex env set AUTH_LOG_LEVEL DEBUG

Logs will appear in the Convex dashboard.

Note that this will log tokens and other sensitive information, so this should only be used when debugging.

Next.js middleware

Enable verbose logging by passing verbose: true to the convexAuthNextjsMiddleware function:

export default convexAuthNextjsMiddleware(optionalHandler, {
  verbose: true,
});

Logs will appear in your next dev terminal, or wherever you're running Next.js.

Related debugging guides

See this guide (opens in a new tab) for debugging auth integraiations with Convex.