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.

SShiftFast Team
Published on November 4, 2026
Clerk Publishable Key: Where to Find It and Fix 'Not Valid' or '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

  1. Open the Clerk Dashboard, go to API keys, and copy the Publishable key. It starts with pk_test_ or pk_live_.
  2. Put it in .env.local in your project root, not in src/: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
  3. Restart next dev.
  4. In production, CI, or Docker, set the same variable for the build step, then rebuild.

Where to find your Clerk publishable key

  1. Sign in to the Clerk Dashboard and open your application.
  2. Go to API keys. Clerk's own error messages link there (https://dashboard.clerk.com/~/api-keys).
  3. Copy the Publishable key. Development instances give a key starting with pk_test_; production instances give one starting with pk_live_.
  4. Paste it into .env.local in 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/sharedMeaning
Publishable key is missing. Ensure that your publishable key is correctly configured. (then a dashboard link)4.23.0The 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.0The same problem, from another check
Publishable key not valid.4.23.0A value exists but isn't a valid key
Publishable key is missing.4.41.1The variable is empty or not set
Publishable key not valid (expected format: pk_test_... or pk_live_...).4.41.1A 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_ZXhhbXBsZS5jbGVyay5hY2NvdW50cy5kZXYk
  • pk: every publishable key starts with it.
  • test or live: 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:

  1. It starts with pk_test_ (development) or pk_live_ (production).
  2. Splitting it on _ gives exactly three parts.
  3. The third part decodes from base64.
  4. The decoded value ends with exactly one $ and contains a dot, like example.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 to CLERK_SECRET_KEY for the server. Without the NEXT_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 a src/ 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.example with pk_test_ and nothing after it, or a made-up value like pk_test_dummy. Neither decodes to a host, so both are rejected. ShiftFast's .env.example is 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 in CLERK_SECRET_KEY, never in a NEXT_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_KEY for 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_ZXhhbXBsZS5jbGVyay5hY2NvdW50cy5kZXYk

It 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/shared source, versions 4.23.0 (used by @clerk/nextjs 7.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, .env location with src/