Agent skill · software engineering · jeremylongshore
clerk-common-errors
Troubleshoot common Clerk errors and issues.
Why this skill is useful
Provides specific troubleshooting steps and code snippets for common Clerk authentication errors that the AI wouldn't reliably generate on its own.
What it needs
Requires clerk installed locally. Requires clerk account access. About 4k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Clerk Common Errors Overview Diagnose and resolve common Clerk authentication errors. Organized by error category with root cause analysis and fix code. Prerequisites Clerk SDK installed Access to Clerk Dashboard for configuration verification Browser developer tools for client-side debugging Instructions Error Category 1: Configuration Errors Clerk: Missing publishableKey ClerkProvider must wrap your application Error Category 2: Authentication Errors formidentifiernotfound formpasswordincorrect sessionexists (Error during sign-in) Error Category 3: Middleware Errors Infinite redirect loop auth() was called but Clerk middleware was not detected Error Category 4: Server/Client Component Errors useUser() in Server Component Hydration mismatch with auth state Error Category 5: Webhook Errors Invalid signature on webhook endpoint Output Identified error category and root cause Working fix code for each common error Diagnostic steps for verification Error Handling Error Cause Quick Fix ------- ------- ----------- Missing publishableKey Env var not set Add NEXTPUBLICCLERKPUBLISHABLEKEY to .env.local auth() not detected Middleware missing/misplaced Move middleware.ts to project root Redirect loop Auth pages not public Add sign-in/sign-up to isPublicRoute matcher Hydration mismatch Server/client state differs Guard with isLoaded check Webhook invalid signature Body parsed before verify Use req.text() not req.json() before wh.verify() Examples Quick Diagnostic Checklist Resources Clerk Error Reference Clerk Debugging Guide Clerk Discord Community Next Steps Proceed to clerk-debug-bundle for comprehensive debugging tools.
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clerk-common-errors--c7983f