diff --git a/docs/references/nextjs/errors/common-errors.mdx b/docs/references/nextjs/errors/common-errors.mdx new file mode 100644 index 0000000000..2e750dd594 --- /dev/null +++ b/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 ``. +- 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.