added common Clerk + Next.js errors and solutions

docs/references/nextjs/errors/common-errors.mdx

@@ -0,0 +1,60 @@
+---
+title: Common Clerk + Next.js Errors
+---
+
+This page lists common errors you may encounter when using Clerk with Next.js, along with explanations and solutions.
+
+## 1. `auth() was called, but no authProvider was found`
+See [auth-was-called.mdx](./auth-was-called.mdx) for details.
+
+## 2. `Missing Clerk Frontend API`
+**Error:**
+```
+Clerk: Missing Clerk Frontend API. Please set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY in your environment.
+```
+**Solution:**
+- Ensure you have set the `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` environment variable in your `.env.local` or deployment environment.
+- Restart your dev server after adding or changing env vars.
+
+## 3. `Missing Clerk Secret Key`
+**Error:**
+```
+Clerk: Missing Clerk Secret Key. Please set CLERK_SECRET_KEY in your environment.
+```
+**Solution:**
+- Set the `CLERK_SECRET_KEY` in your environment (never expose this to the client!).
+- For Vercel, add it in the project settings under Environment Variables.
+
+## 4. `401 Unauthorized` on API routes
+**Possible causes:**
+- The session token is missing or invalid.
+- The API route is not wrapped with Clerk middleware.
+- The frontend and backend are not sharing cookies (check domain and path settings).
+
+**Solution:**
+- Ensure you are using Clerk's middleware in your API routes.
+- Check that cookies are being sent with requests (especially for cross-origin requests).
+- Verify the session token using Clerk helpers.
+
+## 5. `SSR/CSR Mismatch` or "Hydration failed"
+**Possible causes:**
+- Using Clerk hooks/components outside of ClerkProvider.
+- Rendering Clerk components on the server when they require the client.
+
+**Solution:**
+- Always wrap your app in `<ClerkProvider>`.
+- Use Clerk's SSR helpers for server-side rendering.
+- Check the [SSR guide](../rendering-modes.mdx).
+
+## 6. `CORS` errors
+**Possible causes:**
+- API routes are not configured to accept requests from your frontend domain.
+- Cookies are not being sent due to missing credentials config.
+
+**Solution:**
+- Set up CORS headers correctly in your API routes.
+- Use `credentials: 'include'` in your fetch/AJAX requests if needed.
+
+---
+
+If you encounter an error not listed here, check the [Clerk docs](https://clerk.com/docs) or open an issue on GitHub.