Classify authentication failures
Catch failures from sign-in or other Auth.js operations and branch on error.type.
Auth.js · Class
AuthError
AuthError is the base class for all Auth.js errors and extends JavaScript’s Error. It supports a typed error category, optional structured cause data, and formatted server logging through Auth.js’s logger.error option.
How it works
AuthError is the base class for Auth.js failures and extends the standard Error class. Auth.js formats it for server logging, while its type property identifies the specific error category; a cause may also carry structured diagnostic data.
Syntax
class AuthError extends ErrorReturns
An AuthError instance representing an Auth.js error; it extends Error.
Key points
- AuthError is the common parent used across Auth.js error categories.
- Its design favors readable server-side logging rather than direct presentation in the interface.
- The logger.error option is the documented route through which AuthError logging is formatted.
- The cause property is optional and can hold structured diagnostic values.
Common mistakes
- The class is intended for server-side logging; avoid treating its formatted representation as a user-facing message.
- Sign-in failures can throw this class, so authentication calls should be wrapped when the application needs to handle them.
Example: Handle an Auth.js error
import { AuthError } from "next-auth"
try {
await signIn("credentials", formData)
} catch (error) {
if (error instanceof AuthError) {
console.error(error.type)
}
}Catch an authentication failure, confirm that it is an AuthError, and inspect its documented error type.
When to use it
Server-side diagnostics
Pass Auth.js failures through server logging where readable error output is useful.
Preserve root-cause context
Inspect the optional cause and nested err value while diagnosing an underlying failure.
Interview questions
QWhat is AuthError?
AuthError is Auth.js’s base error class and extends Error. It provides a type property containing the applicable ErrorType, and Auth.js formats it for server logging.
Follow-up: What should code inspect to distinguish failures? Use the type property, and inspect cause when structured diagnostic information is needed.
QHow can an application recognize an AuthError?
Use instanceof AuthError in a catch block to identify an Auth.js authentication failure. After identifying it, the application can use error.type to choose an appropriate handling path.
Follow-up: Why should unrelated errors be rethrown? They do not belong to Auth.js’s documented error hierarchy and may indicate programming or infrastructure defects.
QWhat diagnostic information can AuthError carry?
AuthError can have an optional cause property. That cause is a record of unknown values and includes an optional err field containing an Error.
Follow-up: How does AuthError relate to specialized failures? Auth.js defines more specific error classes that extend AuthError, so an AuthError check also covers those subclasses.
Related
ErrorErrorTypeSignInErrorAdapterErrorAccessDeniedCallbackRouteErrorlogger.error