feat(nextjs): point missing and invalid key errors at the Clerk CLI

[djgould]

Description

Part 2 of the keyless→CLI stack (#9491 → #9492 → #9493 → #9487 → #9488), stacked on #9491. Written against main's middleware (keyless mode untouched — that lands in #9493):

• clerkMiddleware() with missing keys throws missingEnvVars (code=missing_env_keys): npx clerk@latest init first, with npx clerk@latest deploy / npx clerk@latest env pull --instance prod guidance for production. The same message is thrown in every environment — the reader knows whether they are developing or deploying better than NODE_ENV does (e.g. next build && next start locally reports production).
• clerkMiddleware() validates the publishable key format upfront, throwing invalidEnvKeys (code=invalid_env_keys). Previously fabricated or mistyped keys surfaced later as a bare Publishable key not valid. — sandbox agent trials showed invented placeholder keys are the most common agent failure mode.
• Three existing dynamic-key test fixtures used placeholder-format keys and now use validly-formatted ones.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🌟 New feature

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 0cddd6d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 18, 2026 8:13pm
swingset	Ready	Preview	Aug 18, 2026 8:13pm

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9492

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9492

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9492

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9492

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9492

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9492

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9492

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9492

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9492

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9492

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9492

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9492

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9492

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9492

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9492

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9492

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9492

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9492

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9492

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9492

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9492

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9492

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9492

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9492

commit: 0cddd6d

[djgould]

Collapsed into the rest of the stack: the invalid-key fix moved to the actual throw site — the fatal messages in parsePublishableKey (#9491, fixes every server SDK at once) — and the missing-key paths keep using the shared errorThrower messages, which now carry the CLI guidance. No nextjs-specific error constants needed. Stack is now #9491 → #9493 → #9487 → #9488.