diff --git a/docs/pages/guides/pages/error.mdx b/docs/pages/guides/pages/error.mdx index 789665bd01..4bd6b833ee 100644 --- a/docs/pages/guides/pages/error.mdx +++ b/docs/pages/guides/pages/error.mdx @@ -11,11 +11,15 @@ In order to override Auth.js's `/api/auth/error` page we have to define our cust ```ts filename="./auth.ts" +import type { NextAuthConfig } from "next-auth" + +const configPages: NextAuthConfig["pages"] = { + error: "/error" +} + const authConfig: NextAuthConfig = { ... - pages: { - error: "/error", - } + pages: configPages ... }; ``` @@ -39,12 +43,13 @@ export default function AuthErrorPage() { Auth.js forwards the following errors as error query parameters in the URL to our custom error page: -| Query Param | Example URL | Description | -| --------------- | --------------------------------- | --------------------------------------------------------------------------------------------- | -| `Configuration` | `/auth/error?error=Configuration` | There is a problem with the server configuration. Check if your options are correct. | -| `AccessDenied` | `/auth/error?error=AccessDenied` | Usually occurs, when you restricted access through the signIn callback, or redirect callback. | -| `Verification` | `/auth/error?error=Verification` | Related to the Email provider. The token has expired or has already been used. | -| `Default` | `/auth/error?error=Default` | Catch all, will apply, if none of the above matched. | +| Query Param | Example URL | Description | +| ------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------- | +| `Configuration` | `/auth/error?error=Configuration` | There is a problem with the server configuration. Check if your options are correct. | +| `AccessDenied` | `/auth/error?error=AccessDenied` | Usually occurs, when you restricted access through the signIn callback, or redirect callback. | +| `CredentialsSignin` | `/auth/error?error=CredentialsSignin` | The user's credentials were rejected by `authorize` | +| `Verification` | `/auth/error?error=Verification` | Related to the Email provider. The token has expired or has already been used. | +| `Default` | `/auth/error?error=Default` | Catch all, will apply, if none of the above matched. | So now we can update our custom error page with it: @@ -54,25 +59,34 @@ So now we can update our custom error page with it: ```tsx filename="app/error/page.tsx" "use client" +import type { ReactNode } from "react" import { useSearchParams } from "next/navigation" +import type { SignInPageErrorParam, ErrorPageParam } from "next-auth" -enum Error { - Configuration = "Configuration", -} +type AuthErrorKey = SignInPageErrorParam | ErrorPageParam -const errorMap = { - [Error.Configuration]: ( +const errorMap: Partial> = { + Configuration: (

There was a problem when trying to authenticate. Please contact us if this error persists. Unique error code:{" "} Configuration

), + CredentialsSignin: ( +

+ There was a problem when trying to sign in with your credentials. Please + contact us if this error persists. Unique error code:{" "} + + CredentialsSignin + +

+ ), } export default function AuthErrorPage() { const search = useSearchParams() - const error = search.get("error") as Error + const error = search.get("error") as AuthErrorKey | null return (
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts index b6653ffe04..de1fa70f79 100644 --- a/packages/core/src/types.ts +++ b/packages/core/src/types.ts @@ -198,10 +198,33 @@ export interface CookiesOptions { webauthnChallenge: Partial } -/** TODO: Check if all these are used/correct */ +/** + * Error types that can occur during the authentication workflow. + * + * These help identify and handle specific issues: + * + * - "Configuration": The authentication setup is misconfigured or missing required options. + * - "AccessDenied": The user doesn’t have permission to access the requested resource. + * - "Verification": Token verification failed—could be expired, malformed, or invalid. + */ export type ErrorPageParam = "Configuration" | "AccessDenied" | "Verification" -/** TODO: Check if all these are used/correct */ +/** + * Sign-in error types used to determine which message to show the user. + * + * These errors help identify what went wrong during the authentication flow: + * + * - "Signin": Something went wrong during the general sign-in process. + * - "OAuthSignin": Couldn't start the OAuth sign-in flow. + * - "OAuthCallbackError": Issue occurred during the OAuth callback. + * - "OAuthCreateAccount": Failed to create a new account using OAuth. + * - "EmailCreateAccount": Failed to create a new account via email provider. + * - "EmailSignin": Problem signing in with email. + * - "Callback": Error during the authentication callback phase. + * - "OAuthAccountNotLinked": Tried to sign in with an OAuth account that isn't linked. + * - "CredentialsSignin": Provided credentials are invalid. + * - "SessionRequired": A session is required but none was found. + */ export type SignInPageErrorParam = | "Signin" | "OAuthSignin" diff --git a/packages/next-auth/src/index.ts b/packages/next-auth/src/index.ts index 8140ef0897..6fb7b87aee 100644 --- a/packages/next-auth/src/index.ts +++ b/packages/next-auth/src/index.ts @@ -100,6 +100,8 @@ export type { Profile, DefaultSession, User, + ErrorPageParam, + SignInPageErrorParam, } from "@auth/core/types" type AppRouteHandlers = Record<