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 10:17pm
swingset	Ready	Preview	Aug 19, 2026 10:17pm

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

🦋 Changeset detected

Latest commit: 5e965b2

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: 5e965b2

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

!snapshot

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

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>

github-actions · 2026-08-19T22:23:15Z

API Changes Report

Generated by Break Check on 2026-08-19T22:23:13.476Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on 5e965b2.}

djgould · 2026-08-19T23:56:06Z

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': minor


I went with minor but i'd appreciate someone else's input

djgould · 2026-08-20T00:10:09Z

+'@clerk/backend': patch
+---
+
+Mark the internal `createBootstrapSignedOutState` as deprecated. It is no longer used by `@clerk/nextjs` and is kept only for older published SDK versions.


tempted to just remove this change and deprecate seperately

brkalow

@djgould can we remove more of the keyless code paths or do we need to retain them for some reason?

We can do this in a follow up!

brkalow · 2026-08-20T02:55:44Z

  const { rest, runningWithClaimedKeys, __internal_scriptsSlot, children } = props;

-  // NOTE: Create or read keys on every render. Usually this means only on hard refresh or hard navigations.
+  // Read-only: the SDK no longer mints keyless applications, it only reads claimed keys from disk.


Do we still need the KeylessProvider?

brkalow · 2026-08-20T02:56:12Z

@@ -52,6 +53,9 @@ export async function ClerkProvider<TUi extends Ui = Ui>(
  ) : undefined;

  if (shouldRunAsKeyless) {


Should we remove more of the keyless code paths here?

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

djgould and others added 3 commits August 19, 2026 15:15

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

c6ee23d

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

docs(backend): align deprecation phrasing with repo convention

5e965b2

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

djgould force-pushed the dg/keyless-cli/1-remove-bootstrap branch from aef1e89 to 5e965b2 Compare August 19, 2026 22:15

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

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

djgould commented Aug 19, 2026

View reviewed changes

djgould commented Aug 20, 2026

View reviewed changes

brkalow approved these changes Aug 20, 2026

View reviewed changes

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!

github-actions Bot commented Aug 19, 2026

Uh oh!

djgould Aug 19, 2026

Uh oh!

djgould Aug 20, 2026 •

edited

Loading

Uh oh!

brkalow left a comment

Uh oh!

brkalow Aug 20, 2026

Uh oh!

brkalow Aug 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -52,6 +53,9 @@ export async function ClerkProvider<TUi extends Ui = Ui>(
		) : undefined;

		if (shouldRunAsKeyless) {

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!

github-actions Bot commented Aug 19, 2026

API Changes Report

Summary

No API Changes Detected

Uh oh!

djgould Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brkalow left a comment

Choose a reason for hiding this comment

Uh oh!

brkalow Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

brkalow Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

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

djgould Aug 20, 2026 •

edited

Loading