Inspect authentication flow
Local development
Auth.js · Pipe
debug
Auth.js’s debug option enables detailed console diagnostics for authentication and database activity. Prefer enabling it during development and protect or sanitize logs because they can contain sensitive information.
How it works
Set the Auth.js debug option to true to emit detailed authentication and database-operation messages through the console. Use it while diagnosing development issues, or combine it with a custom logger when logs must be routed or formatted differently.
Syntax
debug: booleanParameters
| Name | Type | Description |
|---|---|---|
debug | boolean | Boolean flag that enables debug messages for authentication and database operations. |
Key points
- Turn on diagnostics by adding the debug option to the primary Auth.js configuration.
- The default output goes through console methods and exposes substantial authentication-process detail.
- The diagnostic stream covers requests, responses, errors, and database interactions.
- Use a custom logger when the default console destination or format is unsuitable.
- A custom logger supports forwarding messages to an external logging service or applying a project-specific format.
Common mistakes
- Avoid enabling debug in production unless logs are sanitized, because diagnostic output may contain sensitive user information.
- A configured custom logger takes precedence, so changing debug will not control logging while logger methods are supplied.
Example: Enable development debugging
import NextAuth from "next-auth"
export const { handlers, auth } = NextAuth({
debug: process.env.NODE_ENV !== "production",
})Enable diagnostic logging during development while avoiding it in production.
When to use it
Expose request and adapter details
Incident diagnosis
Route logs through a custom logger
Centralized observability
Interview questions
QHow do you enable Auth.js debugging?
Set debug: true in the object passed to NextAuth. Auth.js then uses console methods to report authentication details, including requests, responses, errors, and database activity.
Follow-up: How should production configuration differ? Use a condition such as process.env.NODE_ENV !== "production" so verbose diagnostics are disabled in production.
QHow can debugging output be customized?
Provide a logger object with error, warn, and debug methods in the Auth.js configuration. Those methods receive a code and additional message values, allowing output to be sent to another service or reformatted.
Follow-up: What happens if both options are configured? The custom logger wins and the debug option is ignored.
QWhy should debug logging be restricted in production?
Debug output can include authentication and database requests and responses, as well as errors. Because those details may expose sensitive information, production logs must be handled carefully.
Follow-up: What is a safer default? Enable debugging only outside production and sanitize any diagnostic data that is retained.
Related
loggerAuthConfigWarningCodedebug-enabled