Clerk Publishable Key: Where to Find It and Fix 'Not Valid' or 'Missing' Errors
Where to find your Clerk publishable key (pk_test_ or pk_live_), how to set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, and how to fix "not valid" and "missing" errors.

A Clerk publishable key is the public key that tells Clerk's browser and
server SDKs which Clerk instance your app belongs to; it starts with pk_test_
or pk_live_. You'll find it in the Clerk Dashboard under API keys, and in
Next.js it goes in the NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY environment variable.
Clerk throws a publishable key error when the value it reads from
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is empty ("missing") or isn't shaped like a
Clerk key ("not valid"). The fix is almost always the same: copy the full key
from the API keys page of the Clerk Dashboard into .env.local at the root of
your project, restart the dev server, and in production make sure the variable
is set before next build runs.
The error messages and validation rules below come from the source of Clerk's
@clerk/shared package, which @clerk/nextjs uses, and the build-time behavior
from the Next.js documentation, both checked on 4 November 2026.
Quick fix
- Open the Clerk Dashboard, go to API keys, and copy the Publishable key. It starts with
pk_test_orpk_live_.- Put it in
.env.localin your project root, not insrc/:NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...- Restart
next dev.- In production, CI, or Docker, set the same variable for the build step, then rebuild.
Where to find your Clerk publishable key
- Sign in to the Clerk Dashboard and open your application.
- Go to API keys. Clerk's own error messages link there
(
https://dashboard.clerk.com/~/api-keys). - Copy the Publishable key. Development instances give a key starting
with
pk_test_; production instances give one starting withpk_live_. - Paste it into
.env.localin your project root:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...The secret key (sk_test_ or sk_live_) sits on the same page and belongs in
CLERK_SECRET_KEY, which stays on the server. Alternatively,
npx -y clerk@latest env pull writes both keys to your env file with the
correct variable names.
Which error are you seeing?
The wording depends on your Clerk SDK version. These are the messages in two
versions of the @clerk/shared source; @clerk/nextjs 7.5.12 uses 4.23.0:
| Message | @clerk/shared | Meaning |
|---|---|---|
Publishable key is missing. Ensure that your publishable key is correctly configured. (then a dashboard link) | 4.23.0 | The variable is empty or not set |
Missing publishableKey. You can get your key at https://dashboard.clerk.com/last-active?path=api-keys. | 4.23.0 | The same problem, from another check |
Publishable key not valid. | 4.23.0 | A value exists but isn't a valid key |
Publishable key is missing. | 4.41.1 | The variable is empty or not set |
Publishable key not valid (expected format: pk_test_... or pk_live_...). | 4.41.1 | A value exists but isn't a valid key |
In 4.41.1 both messages are followed by setup steps, including
npx clerk@latest init, which Clerk says "does not need a Clerk account and
writes temporary dev keys".
What a valid Clerk publishable key looks like
A publishable key has three parts separated by underscores:
pk_test_ZXhhbXBsZS5jbGVyay5hY2NvdW50cy5kZXYkpk: every publishable key starts with it.testorlive: a development or a production instance.- The rest: your Clerk Frontend API host plus a
$, encoded in base64.
Clerk's isPublishableKey function accepts a key only if all of these hold:
- It starts with
pk_test_(development) orpk_live_(production). - Splitting it on
_gives exactly three parts. - The third part decodes from base64.
- The decoded value ends with exactly one
$and contains a dot, likeexample.clerk.accounts.dev$.
You can check a key yourself by decoding its last part:
echo 'ZXhhbXBsZS5jbGVyay5hY2NvdW50cy5kZXYk' | base64 -d
# example.clerk.accounts.dev$If that prints your Clerk Frontend API host followed by $, the key's format is
fine and the problem is how it reaches your app.
Fix "Publishable key is missing"
The variable isn't reaching Next.js. Check, in order:
- The name is exact. Next.js apps read
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, next toCLERK_SECRET_KEYfor the server. Without theNEXT_PUBLIC_prefix, Next.js doesn't expose the value to the browser. - The file is in the right folder. Next.js loads
.env*files from the project root. If you use asrc/folder, the docs say the files "should remain in the root of your project". - You restarted the dev server after editing the file.
- Another file isn't overriding it. Next.js checks
process.env, then.env.$(NODE_ENV).local,.env.local,.env.$(NODE_ENV), and finally.env, stopping at the first match. An empty value set earlier in that order wins.
Clerk's docs also offer npx -y clerk@latest env pull, which writes your keys
to your env file with the correct variable names. To try Clerk without an
account, newer SDKs suggest npx clerk@latest init, which writes temporary
development keys.
Fix "Publishable key not valid"
A value arrives but fails one of the four checks above. The usual causes:
- It's still a placeholder. Many starters ship an
.env.examplewithpk_test_and nothing after it, or a made-up value likepk_test_dummy. Neither decodes to a host, so both are rejected. ShiftFast's.env.exampleis one of them. - It was copied incompletely. The key is long; a missing character at the end breaks the base64.
- It's the secret key. Secret keys start with
sk_, and they belong inCLERK_SECRET_KEY, never in aNEXT_PUBLIC_variable. - The hosting dashboard added characters. When you paste the key into a hosting provider's environment settings, don't include quotes or spaces around it.
Fix it in production, CI, and Docker
If the key works locally but not after deploying, the cause is usually when the
variable is read. Next.js inlines NEXT_PUBLIC_ variables "at build time, into
the js bundle", and "after being built, your app will no longer respond to
changes to these environment variables".
- Hosting platforms: set
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYfor the environment that builds the app, then redeploy so the build runs again. Changing the variable without rebuilding has no effect. - Docker: pass the key as a build argument, because the image is built
once and runtime variables come too late. ShiftFast's
Docker guide does this with
ARG NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY. - CI builds that never sign anyone in: a placeholder in the valid format passes Clerk's check without pointing at a real instance:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_ZXhhbXBsZS5jbGVyay5hY2NvdW50cy5kZXYkIt decodes to example.clerk.accounts.dev$, so sign-in won't work with it. Use
your real development key anywhere a person or an end-to-end test signs in.
How ShiftFast handles it
ShiftFast validates its environment variables with a schema, and an empty
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY fails that check with an error naming the
variable. The schema checks that the key isn't empty, not its format, so a
leftover placeholder still reaches Clerk's "not valid" error. Our troubleshooting docs cover this and the
other common setup errors, and Configuration lists every
variable.
If you're setting up organizations next, see multi-tenant auth with Clerk Organizations, or Clerk vs Better Auth for B2B SaaS if you're still choosing a provider.
FAQ
Where do I find my Clerk publishable key?
In the Clerk Dashboard under API keys; see
the steps above. Development
instances give pk_test_ keys and production instances give pk_live_ keys.
Why does my Clerk key work locally but not in production?
Next.js bakes NEXT_PUBLIC_ variables into the JavaScript at build time. If
the variable wasn't set when the production build ran, the deployed app has no
key, even if you added it afterwards. Set it and rebuild.
Is it safe to expose the publishable key?
It's designed to reach the browser: as a NEXT_PUBLIC_ variable, Next.js
inlines it into the JavaScript it sends to users. Keep the secret key
(sk_...) server-only.
Can I use a fake publishable key for tests?
Yes, if it has the valid format and nothing signs in, such as a build or a
unit test. Use a key that decodes to a host ending in $, like the example
above. For end-to-end tests that sign in, use your real development key.
Sources
Checked on 4 November 2026:
@clerk/sharedsource, versions 4.23.0 (used by@clerk/nextjs7.5.12) and 4.41.1:parsePublishableKey,isPublishableKey, the error messages, and the setup guidance- Clerk environment variables:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,CLERK_SECRET_KEY,clerk env pull - Next.js environment variables:
build-time inlining, load order,
.envlocation withsrc/