Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Clerk cannot read its publishable key in a Next.js app

ErrorClerk fails to get the publishable key from the environment variables

Short 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.

  • Applies to Next.js 15, Clerk Next.js SDK, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.local
  2. 2Match what you see, then jump to its fix

    1. 1No 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. 2It 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. 3The 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

What does the error look like?

  • Clerk fails to get the publishable key from the environment variables
  • NEXT_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.local

2Fix

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 pull

3Verify

Restart the dev server so Next.js loads the file again, then open a page that uses ClerkProvider.

npm run dev

Confirmed by clerk.com

Did this fix it?

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 -3

2Fix

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 build

3Verify

Open the deployed site and check that the sign-in components render.

npm run start

Confirmed by nextjs.org

Did this fix it?

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 build

Confirmed by nextjs.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.