feat(nextjs): throw missing-env error instead of keyless bootstrap by djgould · Pull Request #9493 · clerk/javascript

djgould · 2026-08-18T18:21:20Z

Description

In development, when NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY / CLERK_SECRET_KEY are missing, @clerk/nextjs now throws the shared missing-key error (which points to npx clerk@latest init, from #9491) instead of provisioning a keyless application.

All bootstrap entry points throw via the shared errorThrower; the error surfaces in both the dev server log and the dev error page
keylessMiddleware reduced to baseNextMiddleware, so it's deleted
KeylessProvider (kept for the claimed-keys prompt) uses read-only readKeys() instead of getOrCreateKeys() — the SDK never mints applications
Configured keys, claimed keys, and production behavior are unchanged

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

🤖 Generated with Claude Code

vercel · 2026-08-18T18:21:26Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 19, 2026 5:21pm
swingset	Ready	Preview	Aug 19, 2026 5:21pm

changeset-bot · 2026-08-18T18:21:29Z

🦋 Changeset detected

Latest commit: aef1e89

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

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Patch
@clerk/nextjs	Minor
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	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

pkg-pr-new · 2026-08-18T18:36:13Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 92d8817

djgould · 2026-08-18T21:35:05Z

!snapshot

Squashed from the original four commits of this PR (bootstrap removal, import sort, adversarial-review findings, non-interactive CLI wording) during the simple-first stack reorder. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

djgould · 2026-08-19T18:20:45Z

!snapshot

github-actions · 2026-08-19T18:24:00Z

Hey @djgould - the snapshot version command generated the following package versions:

Package	Version
@clerk/astro	4.0.16-snapshot.v20260819182138
@clerk/backend	3.16.9-snapshot.v20260819182138
@clerk/chrome-extension	3.1.73-snapshot.v20260819182138
@clerk/clerk-js	6.29.3-snapshot.v20260819182138
@clerk/electron	0.0.34-snapshot.v20260819182138
@clerk/electron-passkeys	0.0.4-snapshot.v20260819182138
@clerk/eslint-plugin	0.2.1-snapshot.v20260819182138
@clerk/expo	4.5.1-snapshot.v20260819182138
@clerk/expo-google-signin	1.0.2-snapshot.v20260819182138
@clerk/expo-passkeys	2.0.13-snapshot.v20260819182138
@clerk/express	2.1.60-snapshot.v20260819182138
@clerk/fastify	3.1.70-snapshot.v20260819182138
@clerk/headless	0.0.27-snapshot.v20260819182138
@clerk/hono	0.1.70-snapshot.v20260819182138
@clerk/localizations	4.15.5-snapshot.v20260819182138
@clerk/msw	0.0.63-snapshot.v20260819182138
@clerk/nextjs	7.8.0-snapshot.v20260819182138
@clerk/nuxt	3.0.12-snapshot.v20260819182138
@clerk/react	6.14.5-snapshot.v20260819182138
@clerk/react-router	3.6.14-snapshot.v20260819182138
@clerk/shared	4.29.3-snapshot.v20260819182138
@clerk/swingset	0.0.37-snapshot.v20260819182138
@clerk/tanstack-react-start	1.5.5-snapshot.v20260819182138
@clerk/testing	2.2.27-snapshot.v20260819182138
@clerk/ui	1.30.5-snapshot.v20260819182138
@clerk/upgrade	2.0.6-snapshot.v20260819182138
@clerk/vue	2.4.31-snapshot.v20260819182138

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/astro

npm i @clerk/astro@4.0.16-snapshot.v20260819182138 --save-exact

@clerk/backend

npm i @clerk/backend@3.16.9-snapshot.v20260819182138 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.1.73-snapshot.v20260819182138 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.29.3-snapshot.v20260819182138 --save-exact

@clerk/electron

npm i @clerk/electron@0.0.34-snapshot.v20260819182138 --save-exact

@clerk/electron-passkeys

npm i @clerk/electron-passkeys@0.0.4-snapshot.v20260819182138 --save-exact

@clerk/eslint-plugin

npm i @clerk/eslint-plugin@0.2.1-snapshot.v20260819182138 --save-exact

@clerk/expo

npm i @clerk/expo@4.5.1-snapshot.v20260819182138 --save-exact

@clerk/expo-google-signin

npm i @clerk/expo-google-signin@1.0.2-snapshot.v20260819182138 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@2.0.13-snapshot.v20260819182138 --save-exact

@clerk/express

npm i @clerk/express@2.1.60-snapshot.v20260819182138 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.70-snapshot.v20260819182138 --save-exact

@clerk/headless

npm i @clerk/headless@0.0.27-snapshot.v20260819182138 --save-exact

@clerk/hono

npm i @clerk/hono@0.1.70-snapshot.v20260819182138 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.15.5-snapshot.v20260819182138 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.63-snapshot.v20260819182138 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.8.0-snapshot.v20260819182138 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@3.0.12-snapshot.v20260819182138 --save-exact

@clerk/react

npm i @clerk/react@6.14.5-snapshot.v20260819182138 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.6.14-snapshot.v20260819182138 --save-exact

@clerk/shared

npm i @clerk/shared@4.29.3-snapshot.v20260819182138 --save-exact

@clerk/swingset

npm i @clerk/swingset@0.0.37-snapshot.v20260819182138 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.5.5-snapshot.v20260819182138 --save-exact

@clerk/testing

npm i @clerk/testing@2.2.27-snapshot.v20260819182138 --save-exact

@clerk/ui

npm i @clerk/ui@1.30.5-snapshot.v20260819182138 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.6-snapshot.v20260819182138 --save-exact

@clerk/vue

npm i @clerk/vue@2.4.31-snapshot.v20260819182138 --save-exact

djgould mentioned this pull request Aug 18, 2026

feat(nextjs): throw missing-env error instead of keyless bootstrap #9484

Closed

9 tasks

This was referenced Aug 18, 2026

feat(shared): point missing and invalid key errors at the Clerk CLI #9491

Open

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

Closed

github-actions Bot added nextjs backend integration labels Aug 18, 2026

This was referenced Aug 18, 2026

feat(*): remove keyless bootstrap from astro, nuxt, react-router, and tanstack-react-start #9487

Closed

chore(*): deprecate the keyless substrate ahead of removal #9488

Closed

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from bb7e2a9 to d711cd8 Compare August 18, 2026 18:29

vercel Bot deployed to Preview – clerk-js-sandbox August 18, 2026 18:30 View deployment

vercel Bot deployed to Preview – swingset August 18, 2026 18:32 View deployment

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from d711cd8 to f41f7a7 Compare August 18, 2026 20:08

vercel Bot deployed to Preview – clerk-js-sandbox August 18, 2026 20:09 View deployment

vercel Bot deployed to Preview – swingset August 18, 2026 20:10 View deployment

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from f41f7a7 to b0ade20 Compare August 18, 2026 20:11

vercel Bot deployed to Preview – clerk-js-sandbox August 18, 2026 20:12 View deployment

vercel Bot deployed to Preview – swingset August 18, 2026 20:13 View deployment

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from b0ade20 to 92d8817 Compare August 18, 2026 20:40

djgould deleted the branch dg/keyless-cli/2-prod-error August 18, 2026 20:41

djgould closed this Aug 18, 2026

vercel Bot deployed to Preview – clerk-js-sandbox August 18, 2026 20:41 View deployment

djgould reopened this Aug 18, 2026

vercel Bot deployed to Preview – swingset August 18, 2026 20:43 View deployment

This comment has been minimized.

Sign in to view

vercel Bot deployed to Preview – clerk-js-sandbox August 19, 2026 16:05 View deployment

vercel Bot deployed to Preview – swingset August 19, 2026 16:07 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox August 19, 2026 16:33 View deployment

vercel Bot deployed to Preview – swingset August 19, 2026 16:35 View deployment

djgould changed the base branch from dg/keyless-cli/3-invalid-keys to dg/keyless-cli/2-prod-error August 19, 2026 17:10

djgould and others added 3 commits August 19, 2026 10:18

fix(e2e): accept non-2xx readiness for keyless tests without keys

eed1894

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(backend): align deprecation phrasing with repo convention

aef1e89

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from 5073322 to aef1e89 Compare August 19, 2026 17:18

vercel Bot deployed to Preview – clerk-js-sandbox August 19, 2026 17:19 View deployment

vercel Bot deployed to Preview – swingset August 19, 2026 17:21 View deployment

djgould marked this pull request as ready for review August 19, 2026 17:50

djgould requested a review from brkalow August 19, 2026 17:59

Navigation Menu

Uh oh!

feat(nextjs): throw missing-env error instead of keyless bootstrap - #9493

feat(nextjs): throw missing-env error instead of keyless bootstrap#9493
djgould wants to merge 3 commits into
dg/keyless-cli/2-prod-errorfrom
dg/keyless-cli/1-remove-bootstrap

djgould commented Aug 18, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

djgould commented Aug 18, 2026

Uh oh!

This comment has been minimized.

djgould commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

djgould commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

vercel Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

djgould commented Aug 18, 2026

Uh oh!

This comment has been minimized.

djgould commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

djgould commented Aug 18, 2026 •

edited

Loading

vercel Bot commented Aug 18, 2026 •

edited

Loading

changeset-bot Bot commented Aug 18, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 18, 2026 •

edited

Loading