feat: Improved API error page (#5272)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: Bereket Engida <Bekacru@gmail.com>

Author: 3 people

docs/app/docs/[[...slug]]/page.tsx

@@ -35,10 +35,14 @@ export default async function Page({
 	params: Promise<{ slug?: string[] }>;
 }) {
 	const { slug } = await params;
-	const page = source.getPage(slug);
+	let page = source.getPage(slug);
 
 	if (!page) {
-		notFound();
+		if (slug?.[0] === "errors") {
+			page = source.getPage(["errors", "unknown"])!;
+		} else {
+			return notFound();
+		}
 	}
 
 	const MDX = page.data.body;
@@ -75,7 +79,7 @@ export default async function Page({
 							return (
 								<CodeBlockTabs
 									{...props}
-									className="p-0 border-0 rounded-lg bg-fd-secondary"
+									className="p-0 rounded-lg border-0 bg-fd-secondary"
 								>
 									<div {...props}>{props.children}</div>
 								</CodeBlockTabs>
@@ -173,8 +177,14 @@ export async function generateMetadata({
 	params: Promise<{ slug?: string[] }>;
 }) {
 	const { slug } = await params;
-	const page = source.getPage(slug);
-	if (page == null) notFound();
+	let page = source.getPage(slug);
+	if (page == null) {
+		if (slug?.[0] === "errors") {
+			page = source.getPage(["errors", "unknown"])!;
+		} else {
+			return notFound();
+		}
+	}
 	const baseUrl = process.env.NEXT_PUBLIC_URL || process.env.VERCEL_URL;
 	const url = new URL(`${baseUrl}/api/og`);
 	const { title, description } = page.data;

docs/components/floating-ai-search.tsx

@@ -101,7 +101,7 @@ function SearchAIInput(props: ComponentProps<"form"> & { isMobile?: boolean }) {
 	return (
 		<div
 			className={cn(
-				"flex flex-col relative bg-fd-background m-[1px] border border-fd-border rounded-lg shadow-2xl shadow-fd-background",
+				"flex relative flex-col rounded-lg border shadow-2xl bg-fd-background m-[1px] border-fd-border shadow-fd-background",
 				isLoading ? "opacity-50" : "",
 			)}
 		>
@@ -132,12 +132,12 @@ function SearchAIInput(props: ComponentProps<"form"> & { isMobile?: boolean }) {
 						className={cn(
 							buttonVariants({
 								color: "secondary",
-								className: "transition-all rounded-full mt-2 gap-2",
+								className: "gap-2 mt-2 rounded-full transition-all",
 							}),
 						)}
 						onClick={stop}
 					>
-						<Loader2 className="size-4 animate-spin text-fd-muted-foreground" />
+						<Loader2 className="animate-spin size-4 text-fd-muted-foreground" />
 					</button>
 				) : (
 					<button
@@ -146,7 +146,7 @@ function SearchAIInput(props: ComponentProps<"form"> & { isMobile?: boolean }) {
 						className={cn(
 							buttonVariants({
 								color: "secondary",
-								className: "transition-all rounded-full mt-2",
+								className: "mt-2 rounded-full transition-all",
 							}),
 						)}
 						disabled={input.length === 0}
@@ -158,7 +158,7 @@ function SearchAIInput(props: ComponentProps<"form"> & { isMobile?: boolean }) {
 
 			{showSuggestions && (
 				<div className={cn("mt-3", props.isMobile ? "px-3" : "px-4")}>
-					<p className="text-xs font-medium text-fd-muted-foreground mb-2">
+					<p className="mb-2 text-xs font-medium text-fd-muted-foreground">
 						Try asking:
 					</p>
 					<div
@@ -199,7 +199,7 @@ function SearchAIInput(props: ComponentProps<"form"> & { isMobile?: boolean }) {
 					<Popover>
 						<PopoverTrigger asChild>
 							<button
-								className="sm:hidden hover:bg-fd-accent/50 rounded transition-colors"
+								className="rounded transition-colors sm:hidden hover:bg-fd-accent/50"
 								aria-label="Show information"
 							>
 								<InfoIcon className="size-3.5" />
@@ -208,17 +208,17 @@ function SearchAIInput(props: ComponentProps<"form"> & { isMobile?: boolean }) {
 						<PopoverContent
 							side="top"
 							align="end"
-							className="w-auto max-w-44 p-2 text-xs text-pretty"
+							className="p-2 w-auto text-xs max-w-44 text-pretty"
 						>
 							AI can be inaccurate, please verify the information.
 						</PopoverContent>
 					</Popover>
 				</div>
 			)}
 			{!showSuggestions && (
-				<div className="border-t px-4 text-xs text-fd-muted-foreground cursor-pointer bg-fd-accent/40 flex items-center gap-1 mt-2 py-2">
+				<div className="flex gap-1 items-center px-4 py-2 mt-2 text-xs border-t cursor-pointer text-fd-muted-foreground bg-fd-accent/40">
 					<div
-						className="flex items-center gap-1 empty:hidden hover:text-fd-foreground transition-all duration-200 aria-disabled:opacity-50 aria-disabled:cursor-not-allowed"
+						className="flex gap-1 items-center transition-all duration-200 empty:hidden hover:text-fd-foreground aria-disabled:opacity-50 aria-disabled:cursor-not-allowed"
 						role="button"
 						aria-disabled={isLoading}
 						tabIndex={0}
@@ -331,11 +331,11 @@ function Input(props: ComponentProps<"textarea">) {
 				id="nd-ai-input"
 				{...props}
 				className={cn(
-					"resize-none bg-transparent placeholder:text-fd-muted-foreground focus-visible:outline-none",
+					"bg-transparent resize-none placeholder:text-fd-muted-foreground focus-visible:outline-none",
 					shared,
 				)}
 			/>
-			<div ref={ref} className={cn(shared, "break-all invisible")}>
+			<div ref={ref} className={cn(shared, "invisible break-all")}>
 				{`${props.value?.toString() ?? ""}\n`}
 			</div>
 		</div>
@@ -353,8 +353,8 @@ function ThinkingIndicator() {
 			<p className="mb-1 text-sm font-medium text-fd-muted-foreground">
 				BA bot
 			</p>
-			<div className="flex items-end gap-1 text-sm text-fd-muted-foreground">
-				<div className="flex items-center gap-1 opacity-70">
+			<div className="flex gap-1 items-end text-sm text-fd-muted-foreground">
+				<div className="flex gap-1 items-center opacity-70">
 					<span className="inline-block size-1 bg-fd-primary rounded-full animate-bounce [animation-delay:0ms]" />
 					<span className="inline-block size-1 opacity-80 bg-fd-primary rounded-full animate-bounce [animation-delay:150ms]" />
 					<span className="inline-block size-1 bg-fd-primary rounded-full animate-bounce [animation-delay:300ms]" />
@@ -413,11 +413,11 @@ function Message({
 			>
 				{roleName[message.role] ?? "unknown"}
 			</p>
-			<div className="prose text-sm">
+			<div className="text-sm prose">
 				<Markdown text={markdown} />
 			</div>
 			{links && links.length > 0 && (
-				<div className="mt-3 flex flex-col gap-2">
+				<div className="flex flex-col gap-2 mt-3">
 					<p className="text-xs font-medium text-fd-muted-foreground">
 						References:
 					</p>
@@ -426,7 +426,7 @@ function Message({
 							<Link
 								key={i}
 								href={item.url}
-								className="flex items-center gap-2 text-xs rounded-lg border p-2 hover:bg-fd-accent hover:text-fd-accent-foreground transition-colors"
+								className="flex gap-2 items-center p-2 text-xs rounded-lg border transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground"
 								target="_blank"
 								rel="noopener noreferrer"
 							>
@@ -561,11 +561,11 @@ export function AISearchTrigger() {
 					>
 						<div
 							className={cn(
-								"sticky top-0 flex gap-2 items-center py-2",
+								"flex sticky top-0 gap-2 items-center py-2",
 								isMobile ? "w-full" : "w-[min(800px,90vw)]",
 							)}
 						>
-							<div className="flex justify-end w-full items-center">
+							<div className="flex justify-end items-center w-full">
 								<button
 									aria-label="Close"
 									tabIndex={-1}
@@ -587,7 +587,7 @@ export function AISearchTrigger() {
 							className={cn(
 								"overscroll-contain",
 								isMobile
-									? "pt-6 pb-28 px-2 w-full"
+									? "px-2 pt-6 pb-28 w-full"
 									: "py-10 pr-2 w-[min(800px,90vw)]",
 							)}
 							style={{

docs/content/docs/errors/account_already_linked_to_different_user.mdx

@@ -0,0 +1,64 @@
+---
+title: Account already linked to different user
+description: The account is already linked to a different user.
+---
+
+## What is it?
+
+This error occurs during the OAuth flow when attempting to link an OAuth provider account 
+to the currently authenticated user, but that exact provider account is already linked to 
+another user in your project. To prevent account takeover, Better Auth blocks the link and 
+throws this error.
+
+This situation is only possible through the OAuth flow (e.g., Google, GitHub, etc.). It is 
+not triggered by email/password flows on their own.
+
+## How to resolve
+
+### Typical resolutions
+
+* Log in as the user who already has the provider linked, unlink the provider from that account, 
+  then link it to the intended account.
+* If both accounts belong to the same person and you want a single user, merge the accounts: choose 
+  a primary user, move sessions and linked accounts from the secondary user to the primary, then 
+  deactivate or delete the secondary.
+
+### Common Causes
+
+* You previously signed in or signed up using this provider on a different user in the same project.
+* You have two local users (e.g., created via email/password or magic link) and you linked the provider 
+  to one of them; now you are trying to link the same provider to the other.
+* Test/preview environments share the same OAuth provider configuration and database; the provider account 
+  is already linked to a different user record.
+* Data migration or manual database edits left a stale link pointing to the wrong user.
+* You rely on email matching to decide linking, but the actual unique key is the provider account identifier 
+  (e.g., `providerId` + `accountId`). If that mapping exists for another user, linking will be blocked.
+
+### Safer patterns and prevention
+
+* Avoid automatically linking a provider to whichever user is currently signed in unless you explicitly 
+  confirm ownership with the user.
+* If you provide a 'Connect account' UI, clearly communicate which user will receive the link and what to do 
+  if the provider is already linked elsewhere.
+* Consider disabling linking for providers you only want to use for sign-in, to avoid accidental cross-linking.
+
+### Debug locally
+
+* Inspect your `account` database table. You should see rows keyed by 
+  `providerId` (e.g., 'google') and `accountId` (e.g., OIDC `sub`), pointing to a `userId`.
+* Identify which user currently owns the provider link and decide whether to unlink, merge, or keep as-is.
+* Verify your app is connected to the expected database and environment (dev/staging/prod) to avoid confusion 
+  due to shared credentials or misconfigured environment variables.
+
+### Provider considerations
+
+* Ensure you request stable user identifiers from the provider (e.g., OIDC `openid` scope) so `accountId` 
+  remains consistent across sessions.
+* If you changed provider projects/tenants, identifiers may differ; confirm you are linking the correct provider 
+  credentials for the environment.
+
+<Callout type="info">
+  This error is a security safeguard. It prevents an OAuth identity that already belongs to one user 
+  from being attached to another user without explicit action. If a legitimate merge is intended, perform 
+  a controlled merge or unlink-then-link flow rather than bypassing the check.
+</Callout>

docs/content/docs/errors/email_doesn't_match.mdx

@@ -0,0 +1,34 @@
+---
+title: Email doesn't match
+description: The email doesn't match the email of the account.
+---
+
+## What is it?
+
+This error appears only during OAuth account linking. It happens when a signed-in user tries to
+link an OAuth provider account, but the email returned by the provider does not match the email
+on the currently authenticated user (or the email you expect for that user). To prevent
+accidental cross-account linking or account takeover, Better Auth blocks the link when emails do
+not align.
+
+This does not occur during normal OAuth sign-in; it is specific to the linking flow.
+
+## Common Causes
+
+* The user is logged into the provider with a different email (e.g., work vs personal).
+* The provider returns an unverified or secondary email that differs from the app account email.
+* Email normalization differences (case sensitivity, dots/aliases on Gmail) cause a mismatch.
+* The user's email changed in your app or at the provider since the original account was created.
+
+## How to resolve
+
+### Ask the user to align identities
+
+* Have the user switch to the correct provider account that uses the same email as their app account.
+* Alternatively, update the app account email to the intended email (if your product allows it) and retry linking.
+
+### Debug locally
+
+* Log the current user's email in your app and the email returned by the provider profile.
+* Inspect whether the provider email is verified/primary and whether any normalization is applied.
+* Confirm which provider credentials (dev/staging/prod) are in use and that the returned identity is the expected one.

docs/content/docs/errors/email_not_found.mdx

@@ -0,0 +1,38 @@
+---
+title: Email not found
+description: The provider did not return an email address.
+---
+
+## What is it?
+
+This error occurs during the OAuth flow when the provider does not return an email address for the user. 
+Better Auth uses the email from the provider to identify or create a user account. If the provider omits 
+the email (or returns it as empty/undefined), we cannot proceed and the request is rejected.
+
+This error is only possible through OAuth providers. It will not occur in non-OAuth flows.
+
+## Common Causes
+
+* Missing or insufficient scopes in the provider configuration (e.g., not requesting `email`).
+* The user's email is private or not exposed by default (e.g., GitHub private email).
+* The provider returns email only via a separate endpoint and the scope/API call to fetch it was not enabled 
+  (e.g., GitHub `user:email`).
+* Provider project or tenant misconfiguration (consent screen, admin consent, restricted claims/attributes).
+* Using different credentials between environments (preview/staging/prod) that do not request the same scopes.
+
+## How to resolve
+
+### Request the correct scopes
+
+* Ensure your provider configuration requests the email-related scopes.
+
+### Verify provider app/dashboard settings
+
+* In the provider's dashboard, confirm the app has permission to request email and the consent screen allows it.
+
+### Debug locally
+
+* Inspect the outgoing authorize request to confirm the scopes include `email` where required.
+* Inspect the callback payload (query, `id_token` claims, userinfo response) to see if an email claim exists.
+* Log the provider profile object received by your callback handler to verify whether `email` is present.
+* Check which environment's provider credentials are in use and whether scopes differ across environments.

docs/content/docs/errors/index.mdx

@@ -0,0 +1,20 @@
+---
+title: Errors
+description: Errors that can occur in Better Auth.
+---
+
+This section contains all the errors that cause you to be redirected to the `/api/auth/error` page. 
+
+## List of errors
+
+- [Invalid callback request](/docs/errors/invalid_callback_request)
+- [State not found](/docs/errors/state_not_found)
+- [Account already linked to different user](/docs/errors/account_already_linked_to_different_user)
+- [Email doesn't match](/docs/errors/email_doesn't_match)
+- [Email not found](/docs/errors/email_not_found)
+- [No callback URL](/docs/errors/no_callback_url)
+- [No code](/docs/errors/no_code)
+- [OAuth provider not found](/docs/errors/oauth_provider_not_found)
+- [Unable to link account](/docs/errors/unable_to_link_account)
+- [Unable to get user info](/docs/errors/unable_to_get_user_info)
+- [State mismatch](/docs/errors/state_mismatch)

docs/content/docs/errors/invalid_callback_request.mdx

@@ -0,0 +1,47 @@
+---
+title: Invalid callback request
+description: The callback request is invalid.
+---
+
+## What is it?
+
+This error is thrown during the OAuth callback when the incoming request cannot be parsed or is missing
+required fields. 
+
+## Common Causes
+
+* Query or body parameters were stripped by a reverse proxy, CDN, or framework rewrite.
+* Double-encoding or improper URL encoding of parameters causes parsing to fail.
+* Callback URL mismatch at the provider triggers an intermediate redirect that drops parameters.
+* Middleware or route grouping sends the request to a different handler than intended.
+* Very long URLs get truncated by an intermediary (rare but possible with some proxies).
+
+## How to resolve
+
+### Verify callback method and parameters
+
+* Ensure your provider is configured to use the method your route expects (commonly GET with query parameters for Authorization Code flow).
+* Confirm the callback includes required parameters (e.g., `code` and `state` for standard OAuth flows).
+
+### Preserve query/body through infrastructure
+
+* Check that reverse proxies (Vercel, Cloudflare, Nginx) and app rewrites forward the full query string and request body intact.
+* If middleware intercepts or rewrites the callback, make sure it forwards all parameters without modification.
+
+### Debug locally
+
+* In DevTools → Network, inspect the callback request and verify parameters are present and well-formed.
+* Compare dev/staging/prod credentials to ensure there are no environment differences causing different flows or endpoints.
+
+### Edge cases to consider
+
+* Mobile/WebView or deep-link flows can drop query parameters during handoff.
+* Some providers can return parameters in fragments; your server will not receive fragments—ensure the provider uses query/body for server-side callbacks.
+* Multiple redirects (including HTTP → HTTPS) can lose parameters if not configured correctly.
+
+<Callout type="info">
+    Callback parameters are normally handled automatically by Better Auth. If this error appears, it often
+    indicates manual access to the `/api/auth/callback` route, a proxy/redirect that stripped parameters,
+    or an integration mismatch. Double-check provider settings and infrastructure rewrites to ensure the
+    full request reaches the callback unchanged.
+</Callout>