Clerk cannot read its publishable key in a Next.js app
Clerk fails to get the publishable key from the environment variablesShort answer
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY. The key is missing when the variable has another name, the .env.local file is not in the project root, the dev server was not restarted, or the host did not have the variable when next build ran, because NEXT_PUBLIC values are inlined at build time.
Fix it fast
1Find out which cause you have
Check which env files exist and whether the Clerk key name is in .env.local, without printing secret values.
ls -a | grep env grep -c "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY" .env.local2Match what you see, then jump to its fix
- 1
No match in .env.local, or the file sits inside src/ or another folder.The variable has the wrong name or the env file is in the wrong placeFix - 2
It works on your machine; the Netlify or other deployed site fails, and the variable was added to the host after the last build.The host built the app without the variableFix - 3
The key is defined in the environment, but code reads it with process.env[name], or the variable has no NEXT_PUBLIC_ prefix and is read in browser code.The key is read through a dynamic lookup or without the prefixFix
- 1
What does the error look like?
Clerk fails to get the publishable key from the environment variablesNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Cause 1 of 3
The variable has the wrong name or the env file is in the wrong place
1Check
Clerk expects NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY. Next.js loads .env files from the project root only, even when the app uses a src folder.
find . -maxdepth 2 -name ".env*" -not -path "./node_modules/*"
grep -o "^[A-Z_]*CLERK[A-Z_]*" .env.local2Fix
Put both variables in .env.local in the project root with these exact names. The Clerk CLI can write them for you.
npx -y clerk@latest env pull3Verify
Restart the dev server so Next.js loads the file again, then open a page that uses ClerkProvider.
npm run devConfirmed by clerk.com
Cause 2 of 3
The host built the app without the variable
1Check
NEXT_PUBLIC_ variables are replaced with their values when next build runs, and a built app no longer reacts to later changes.
grep -rl "pk_" .next/static 2>/dev/null | head -32Fix
Set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY (and CLERK_SECRET_KEY) in the host's environment settings, then trigger a new build instead of only a redeploy. Use the pk_live_ key for a production instance.
# after saving the variables in the host dashboard
npm run build3Verify
Open the deployed site and check that the sign-in components render.
npm run startConfirmed by nextjs.org
Cause 3 of 3
The key is read through a dynamic lookup or without the prefix
1Check
Without the NEXT_PUBLIC_ prefix a value stays in the Node.js environment. Dynamic lookups such as process.env[varName] are not inlined either.
grep -rn "process.env\[" --include="*.ts" --include="*.tsx" .2Fix
Read the public key with the full literal name and keep CLERK_SECRET_KEY on the server only.
const key = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY;3Verify
Rebuild and reload the page.
npm run buildConfirmed by nextjs.org
How do I stop it coming back?
- Add the Clerk variables to the host before the first deploy and rebuild after any change.
- Use test keys (pk_test_) in development and live keys (pk_live_) only in the production instance.
- Keep .env files out of git; the Next.js default template already ignores them.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fixWeb apps
NextAuth sends the user to ?error=AccessDenied after Google sign in
error=AccessDenied
AccessDenied is not a Google or MongoDB error.
2 causes, each with a fix