gh-jezweb-claude-skills-skills-clerk-auth/references/common-errors.md

Clerk Authentication - Common Errors & Solutions

Last Updated: 2025-10-22

This document provides detailed troubleshooting for all 10 documented Clerk authentication issues.

---

Error #1: Missing Clerk Secret Key

Symptoms

``` Error: Missing Clerk Secret Key or API Key ```

Why It Happens

• `CLERK_SECRET_KEY` environment variable not set
• Environment file not loaded
• Wrong environment file name

Solutions

Next.js:

1. Create `.env.local` in project root
2. Add: `CLERK_SECRET_KEY=sk_test_...`
3. Restart dev server

Cloudflare Workers:

1. Local: Create `.dev.vars` with `CLERK_SECRET_KEY=sk_test_...`
2. Production: Run `wrangler secret put CLERK_SECRET_KEY`

Prevention

• Always set secret key before running app
• Verify with: `echo $CLERK_SECRET_KEY` (should be empty - it's private!)
• Check environment is loading: add `console.log(!!process.env.CLERK_SECRET_KEY)`

Source: https://stackoverflow.com/questions/77620604

---

Error #2: API Key → Secret Key Migration (Core 2)

Symptoms

``` Warning: apiKey is deprecated, use secretKey instead TypeError: Cannot read properties of undefined ```

Why It Happens

• Upgrading from @clerk/backend v1 to v2 (Core 2)
• Old code uses `apiKey` parameter
• Breaking change in Core 2

Solutions

Before (v1): ```typescript const clerk = createClerkClient({ apiKey: process.env.CLERK_API_KEY // ❌ Deprecated }) ```

After (v2): ```typescript const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY // ✅ Correct }) ```

Prevention

• Use `secretKey` in all new code
• Search codebase for `apiKey:` and replace with `secretKey:`
• Update environment variable name from `CLERK_API_KEY` to `CLERK_SECRET_KEY`

Source: https://clerk.com/docs/upgrade-guides/core-2/backend

---

Error #3: JWKS Cache Race Condition

Symptoms

``` Error: No JWK available Token verification fails intermittently ```

Why It Happens

• Race condition in older @clerk/backend versions
• JWKS cache not populated before verification
• Fixed in recent versions

Solutions

Update Package: ```bash npm install @clerk/backend@latest

Ensure version is 2.17.2 or later

```

Verify Version: ```bash npm list @clerk/backend ```

Prevention

• Always use latest stable @clerk/backend version
• This issue is fixed in modern versions

Source: https://github.com/clerk/javascript/blob/main/packages/backend/CHANGELOG.md

---

Error #4: Missing authorizedParties (CSRF Vulnerability)

Symptoms

• No error, but security vulnerability
• Tokens from other domains accepted
• CSRF attacks possible

Why It Happens

• `authorizedParties` not set in `verifyToken()`
• Clerk accepts tokens from any domain by default

Solutions

Always Set authorizedParties: ```typescript const { data, error } = await verifyToken(token, { secretKey: env.CLERK_SECRET_KEY, authorizedParties: [ 'http://localhost:5173', // Development 'https://yourdomain.com', // Production ], // ✅ Required for security }) ```

Prevention

• Always set `authorizedParties` in production
• List all domains that should be able to make requests
• Never use wildcard or leave empty

Source: https://clerk.com/docs/reference/backend/verify-token

---

Error #5: Import Path Changes (Core 2 Upgrade)

Symptoms

``` Error: Cannot find module '@clerk/backend' Module not found: Can't resolve '@clerk/backend/errors' ```

Why It Happens

• Import paths changed in Core 2
• Old imports don't work in new version

Solutions

Update Imports: ```typescript // Before (v1) import { TokenVerificationError } from '@clerk/backend'

// After (v2) import { TokenVerificationError } from '@clerk/backend/errors' ```

Common Path Changes

Old Path	New Path
`@clerk/backend` (errors)	`@clerk/backend/errors`
`@clerk/backend` (types)	`@clerk/backend/types`

Prevention

• Follow official migration guide
• Update all imports when upgrading

Source: https://clerk.com/docs/upgrade-guides/core-2/backend

---

Error #6: JWT Size Limit Exceeded

Symptoms

``` Error: Token exceeds maximum size Session token too large ```

Why It Happens

• Custom JWT claims exceed 1.2KB limit
• Too much data in `publicMetadata`
• Clerk's default claims + your claims > 1.2KB

Solutions

Reduce Custom Claims: ```json { "email": "{{user.primary_email_address}}", "role": "{{user.public_metadata.role}}" } ```

Store Large Data in Database:

• Use JWT for minimal claims (user ID, role)
• Store profile data, preferences in your database
• Fetch after authentication

Prevention

• Keep custom claims minimal
• Use database for large/complex data
• Monitor token size during development

Source: https://clerk.com/docs/backend-requests/making/custom-session-token

---

Error #7: Deprecated API Version v1

Symptoms

``` Warning: API version v1 is deprecated Please upgrade to API version 2025-04-10 ```

Why It Happens

• Using old SDK version
• API version 1 deprecated April 2025

Solutions

Update SDKs: ```bash npm install @clerk/nextjs@latest npm install @clerk/backend@latest npm install @clerk/clerk-react@latest ```

Verify Versions:

• @clerk/nextjs: 6.0.0+
• @clerk/backend: 2.0.0+
• @clerk/clerk-react: 5.0.0+

Prevention

• Keep SDKs updated
• Use latest stable versions
• Follow deprecation warnings

Source: https://clerk.com/docs/upgrade-guides/core-2/backend

---

Error #8: ClerkProvider JSX Component Error

Symptoms

``` Error: 'ClerkProvider' cannot be used as a JSX component Its element type 'ReactElement<any, any> | Component<...>' is not a valid JSX element ```

Why It Happens

• React version mismatch
• @clerk/clerk-react not compatible with React version
• TypeScript type conflicts

Solutions

Update Packages: ```bash npm install @clerk/clerk-react@latest react@latest react-dom@latest ```

Ensure Compatibility:

• React 19: Use @clerk/clerk-react@5.51.0+
• React 18: Use @clerk/clerk-react@5.0.0+

Prevention

• Keep React and Clerk packages in sync
• Use compatible versions

Source: https://stackoverflow.com/questions/79265537

---

Error #9: Async auth() Helper Confusion

Symptoms

``` Error: auth() is not a function TypeError: Cannot read properties of undefined ```

Why It Happens

• @clerk/nextjs v6 made `auth()` async (breaking change)
• Old code doesn't await `auth()`

Solutions

Before (v5): ```typescript const { userId } = auth() // ❌ Sync in v5 ```

After (v6): ```typescript const { userId } = await auth() // ✅ Async in v6 ```

All Affected Code

• `const { userId } = await auth()`
• `const user = await currentUser()`
• `await auth.protect()` (in middleware)

Prevention

• Always await auth-related functions in v6+
• Update all instances when upgrading

Source: https://clerk.com/changelog/2024-10-22-clerk-nextjs-v6

---

Error #10: Environment Variable Misconfiguration

Symptoms

``` Error: Missing Publishable Key Warning: Secret key exposed to client ```

Why It Happens

• Wrong environment variable prefix
• Secrets committed to version control
• Environment file not loaded

Solutions

Next.js Prefix Rules:

• Client variables: `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
• Server variables: `CLERK_SECRET_KEY` (no prefix!)

Vite Prefix Rules:

• Client variables: `VITE_CLERK_PUBLISHABLE_KEY`

Cloudflare Workers:

• Local: `.dev.vars` file
• Production: `wrangler secret put CLERK_SECRET_KEY`

Prevention Checklist

• Use correct prefix for framework
• Never use `NEXT_PUBLIC_` or `VITE_` for secrets
• Add `.env.local` and `.dev.vars` to `.gitignore`
• Use different keys for dev and production
• Restart dev server after changing env vars

Source: General best practices

---

Error #11: 431 Request Header Fields Too Large (Vite Dev Mode)

Symptoms

431 Request Header Fields Too Large
Failed to load resource: the server responded with a status of 431 ()

Happens when:

• Signing in to your Vite app in development mode
• After adding custom JWT claims
• URL contains very long __clerk_handshake=... parameter

Why It Happens

• Clerk's authentication handshake passes a JWT token in the URL as __clerk_handshake=...
• Vite dev server (Node.js http) has default 8KB request header limit
• Clerk development tokens are larger than production tokens
• Custom JWT claims increase handshake token size
• Long URLs with JWT tokens exceed Vite's header limit

Solutions

Solution 1: Increase Node.js Header Limit (Recommended)

Update package.json:

{
  "scripts": {
    "dev": "NODE_OPTIONS='--max-http-header-size=32768' vite",
    "build": "vite build"
  }
}

This increases the limit from 8KB to 32KB.

For Windows PowerShell:

{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS=--max-http-header-size=32768 vite"
  }
}

Install cross-env: npm install -D cross-env

Solution 2: Temporary Workaround

Clear browser state:

1. Open DevTools (F12)
2. Right-click refresh button → "Empty Cache and Hard Reload"
3. Or: Application tab → Clear all storage
4. Sign out and sign back in

This removes the problematic handshake token and forces Clerk to create a fresh one.

What DOESN'T Work

❌ This won't fix it:

// vite.config.ts
export default defineConfig({
  server: {
    headers: {
      'Cache-Control': 'no-cache', // Wrong - this sets RESPONSE headers
    },
  },
})

The error is about REQUEST headers (incoming), not RESPONSE headers (outgoing).

Prevention

• Expect this error when testing custom JWT claims in dev mode
• Set NODE_OPTIONS in package.json from the start
• Keep custom claims minimal during development
• Production deployments (Cloudflare Workers, Vercel) don't have this issue

Difference from Error #6

Error #6 (JWT Size Limit Exceeded):

• About session token size in cookies
• 1.2KB limit for custom claims
• Affects production
• Browser cookie size limit

Error #11 (431 Header Error):

• About handshake token size in URL parameters
• 8KB default limit (increase to 32KB)
• Only affects Vite dev mode
• Node.js HTTP server limit

Why Production Isn't Affected

• Production builds don't use Vite dev server
• Cloudflare Workers, Vercel, Netlify have higher header limits
• Production tokens are smaller (no dev overhead)
• Handshake flow is optimized in production

Source: Real-world developer experience with Vite + Clerk + Custom JWT claims

---

Quick Debugging Checklist

When auth isn't working:

1. Check Environment Variables

   • `CLERK_SECRET_KEY` set?
   • `CLERK_PUBLISHABLE_KEY` or `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` set?
   • Correct prefix for framework?
   • Dev server restarted after changes?

2. Check Package Versions

   • Using latest stable versions?
   • React version compatible with Clerk?
   • All Clerk packages same major version?

3. Check Code Patterns

   • `auth()` being awaited? (v6+)
   • `authorizedParties` set in `verifyToken()`?
   • `isLoaded` checked before rendering?
   • Using `secretKey` not `apiKey`?

4. Check Network

   • Token in `Authorization: Bearer ` header?
   • CORS configured if API is different domain?
   • Clerk Dashboard shows API requests?

5. Check Clerk Dashboard

   • Application configured correctly?
   • Development/production keys match environment?
   • Custom JWT template valid?
   • Webhooks configured if using?

---

Still Having Issues?

1. Check official Clerk docs: https://clerk.com/docs
2. Search Clerk Discord: https://clerk.com/discord
3. File GitHub issue: https://github.com/clerk/javascript/issues
4. Check Clerk status: https://status.clerk.com

---

Error #12: Deprecated Redirect URL Props

Symptoms

Clerk: The prop "afterSignInUrl" is deprecated and should be replaced with the new "fallbackRedirectUrl" or "forceRedirectUrl" props instead.
Clerk: The prop "afterSignUpUrl" is deprecated and should be replaced with the new "fallbackRedirectUrl" or "forceRedirectUrl" props instead.

Appears in:

• Browser console
• Development mode
• When using <SignIn> or <SignUp> components from @clerk/clerk-react

Why It Happens

• Clerk updated redirect prop naming in v5.x for clarity
• Old props: afterSignInUrl, afterSignUpUrl
• New props: fallbackRedirectUrl, forceRedirectUrl
• Old props still work but trigger deprecation warnings

Solution

Replace deprecated props:

❌ Old (Deprecated):

<SignIn
  afterSignInUrl="/"
  signUpUrl="/signup"
/>

<SignUp
  afterSignUpUrl="/"
  signInUrl="/login"
/>

✅ New (Recommended):

<SignIn
  fallbackRedirectUrl="/"
  signUpUrl="/signup"
/>

<SignUp
  fallbackRedirectUrl="/"
  signInUrl="/login"
/>

Choosing Between fallbackRedirectUrl and forceRedirectUrl

Use fallbackRedirectUrl (Most Common):

• Used as a fallback if no redirect URL is in query params
• Allows Clerk to use redirect_url from query string first
• More flexible for return-to-previous-page flows
• Recommended for most use cases

Use forceRedirectUrl (Rare):

• Always redirects here, ignoring query params
• Used when you want strict control
• Overrides any redirect_url in query string
• Use only when you need to force a specific destination

Example: Complete Migration

// LoginPage.tsx
import { SignIn } from '@clerk/clerk-react';

export function LoginPage() {
  return (
    <SignIn
      routing="path"
      path="/login"
      signUpUrl="/signup"
      fallbackRedirectUrl="/"  // ✅ Use this instead of afterSignInUrl
      appearance={{
        elements: {
          rootBox: 'mx-auto',
          card: 'shadow-lg',
        },
      }}
    />
  );
}

// SignupPage.tsx
import { SignUp } from '@clerk/clerk-react';

export function SignupPage() {
  return (
    <SignUp
      routing="path"
      path="/signup"
      signInUrl="/login"
      fallbackRedirectUrl="/"  // ✅ Use this instead of afterSignUpUrl
      appearance={{
        elements: {
          rootBox: 'mx-auto',
          card: 'shadow-lg',
        },
      }}
    />
  );
}

Migration Checklist

• Search codebase for afterSignInUrl
• Replace with fallbackRedirectUrl
• Search codebase for afterSignUpUrl
• Replace with fallbackRedirectUrl
• Test redirect flow after sign in
• Test redirect flow after sign up
• Verify no console warnings

Why This Matters

Clarity: The new naming makes it clear these are fallback/default redirects Future-Proofing: Old props may be removed in future major versions Best Practices: Using current APIs ensures compatibility with new features

Source: Clerk v5.x Changelog & Official Migration Guide Reference: https://clerk.com/docs/guides/custom-redirects#redirect-url-props

---

Error #12 (Deprecated Redirect Props):

• About redirect URL prop naming
• Simple find-replace fix
• Use fallbackRedirectUrl for most cases
• Only affects React-based projects