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

.changeset/cli-error-copy.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update missing and invalid key error messages to recommend the Clerk CLI: `npx clerk@latest init` creates a Clerk application and writes the required keys to your env file. The messages warn against inventing placeholder keys and keep the Dashboard link for existing applications.

.changeset/keyless-bootstrap-state-deprecated.md

@@ -0,0 +1,5 @@
+---
+'@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.

.changeset/keyless-cli-init-error.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': minor
+---
+
+In development, missing Clerk keys no longer activate keyless mode. When `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` are not set, the SDK now throws an error directing you to run `npx clerk@latest init`, which provisions a Clerk application and writes the keys to `.env.local`. Keyless credentials stored in the development keyless cookie are no longer read. Existing apps with configured or claimed keys are unaffected.

.changeset/nextjs-cli-key-errors.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+`clerkMiddleware()` now points key misconfiguration at the Clerk CLI: missing keys outside development throw a deploy-oriented error recommending `npx clerk@latest deploy` (`code=missing_env_keys_production`), and the publishable key format is validated upfront, throwing `npx clerk@latest init` guidance in development or `npx clerk@latest env pull --instance prod` guidance in production (`code=invalid_env_keys`, `code=invalid_env_keys_production`) instead of failing later with `Publishable key not valid.`

integration/tests/next-middleware-keyless.test.ts

@@ -27,9 +27,11 @@ test.describe('Keyless mode | middleware authorization @nextjs', () => {
     await app.teardown();
   });
 
-  test('auth.protect() in middleware redirects to sign-in during keyless bootstrap', async ({ page }) => {
-    await page.goto(`${app.serverUrl}/protected`);
-    await page.waitForURL(/\/sign-in/);
-    await expect(page.getByTestId('protected')).not.toBeVisible();
+  test('requests without keys fail with the missing env vars error instead of keyless bootstrap', async ({ page }) => {
+    const response = await page.goto(`${app.serverUrl}/protected`);
+    expect(response?.status()).toBe(500);
+    const content = await page.content();
+    expect(content).toContain('Missing environment variables');
+    expect(content).toContain('npx clerk@latest init');
   });
 });

integration/tests/next-quickstart-keyless.test.ts

@@ -1,9 +1,12 @@
+import * as path from 'node:path';
+
 import { expect, test } from '@playwright/test';
 
 import type { Application } from '../models/application';
 import { appConfigs } from '../presets';
+import { fs } from '../scripts';
 import { createTestUtils } from '../testUtils';
-import { mockClaimedInstanceEnvironmentCall, testToggleCollapsePopoverAndClaim } from '../testUtils/keylessHelpers';
+import { mockClaimedInstanceEnvironmentCall } from '../testUtils/keylessHelpers';
 
 const commonSetup = appConfigs.next.appRouterQuickstart.clone();
 
@@ -17,87 +20,56 @@ test.describe('Keyless mode @quickstart', () => {
   });
 
   let app: Application;
-  let dashboardUrl = 'https://dashboard.clerk.com/';
 
   test.beforeAll(async () => {
     app = await commonSetup.commit();
     await app.setup();
     await app.withEnv(appConfigs.envs.withKeyless);
-    if (appConfigs.envs.withKeyless.privateVariables.get('CLERK_API_URL')?.includes('clerkstage')) {
-      dashboardUrl = 'https://dashboard.clerkstage.dev/';
-    }
     await app.dev();
   });
 
   test.afterAll(async () => {
     await app.teardown();
   });
 
-  test('Navigates to non-existent page (/_not-found) without a infinite redirect loop.', async ({ page, context }) => {
-    const u = createTestUtils({ app, page, context });
-    await u.page.goToAppHome();
-    await u.page.waitForClerkJsLoaded();
-    await u.po.expect.toBeSignedOut();
-
-    await u.po.keylessPopover.waitForMounted();
-
-    const redirectMap = new Map<string, number>();
-    page.on('request', request => {
-      // Only count GET requests since Next.js server actions are sent with POST requests.
-      if (request.method() === 'GET') {
-        const url = request.url();
-        redirectMap.set(url, (redirectMap.get(url) || 0) + 1);
-        expect(redirectMap.get(url)).toBeLessThanOrEqual(1);
-      }
-    });
-
-    await u.page.goToRelative('/something');
-    await u.page.waitForAppUrl('/something');
-  });
-
-  test('Toggle collapse popover and claim.', async ({ page, context }) => {
-    await testToggleCollapsePopoverAndClaim({ page, context, app, dashboardUrl, framework: 'nextjs' });
-  });
-
-  test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', async ({
+  test('Without keys, the app fails with the missing env vars error instead of keyless bootstrap.', async ({
     page,
-    context,
   }) => {
-    await mockClaimedInstanceEnvironmentCall(page);
-    const u = createTestUtils({ app, page, context });
-    await u.page.goToAppHome();
-    await u.page.waitForClerkJsLoaded();
-
-    await u.po.keylessPopover.waitForMounted();
-    expect(await u.po.keylessPopover.isExpanded()).toBe(true);
-    await expect(u.po.keylessPopover.promptToUseClaimedKeys()).toBeVisible();
-
-    const href = await u.po.keylessPopover.promptToUseClaimedKeys().getAttribute('href');
-    expect(href).toBeTruthy();
-    expect(href).toContain(dashboardUrl);
+    const response = await page.goto(`${app.serverUrl}/`);
+    expect(response?.status()).toBe(500);
+    const content = await page.content();
+    expect(content).toContain('Missing environment variables');
+    expect(content).toContain('npx clerk@latest init');
   });
 
-  test('Claimed application with keys inside .env, on dismiss, keyless prompt is removed.', async ({
+  test('Claimed application with keys inside .env mounts the keyless prompt; on dismiss, it is removed.', async ({
     page,
     context,
   }) => {
-    await mockClaimedInstanceEnvironmentCall(page);
-    const u = createTestUtils({ app, page, context });
-    await u.page.goToAppHome();
-
-    await u.po.keylessPopover.waitForMounted();
-    await expect(await u.po.keylessPopover.promptToUseClaimedKeys()).toBeVisible();
-
     /**
-     * Copy keys from `.clerk/.tmp/keyless.json to `.env`
+     * Seed claimed keyless state directly: the SDK no longer mints keys, so write the
+     * keys fixture to `.clerk/.tmp/keyless.json` and copy the matching keys into `.env`.
      */
+    const publishableKey = appConfigs.envs.withEmailCodes.publicVariables.get('CLERK_PUBLISHABLE_KEY');
+    const secretKey = appConfigs.envs.withEmailCodes.privateVariables.get('CLERK_SECRET_KEY');
+    await fs.ensureDir(path.join(app.appDir, '.clerk', '.tmp'));
+    await fs.writeJSON(path.join(app.appDir, '.clerk', '.tmp', 'keyless.json'), {
+      publishableKey,
+      secretKey,
+      claimUrl: 'https://dashboard.clerk.com/apps/claim',
+      apiKeysUrl: 'https://dashboard.clerk.com/last-active?path=api-keys',
+    });
     await app.keylessToEnv();
     /**
      * wait a bit for the server to load the new env file
      */
     await page.waitForTimeout(5_000);
 
-    await page.reload();
+    await mockClaimedInstanceEnvironmentCall(page);
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToAppHome();
+    await u.page.waitForClerkJsLoaded();
+
     await u.po.keylessPopover.waitForMounted();
     await u.po.keylessPopover.promptToDismiss().click();
 

packages/backend/src/__tests__/createRedirect.test.ts

@@ -28,7 +28,7 @@ describe('redirect(redirectAdapter)', () => {
       } as any);
 
       expect(() => redirectToSignIn({ returnBackUrl })).toThrowError(
-        '@clerk/backend: Missing publishableKey. You can get your key at https://dashboard.clerk.com/last-active?path=api-keys.',
+        '@clerk/backend: Missing publishableKey. To set up Clerk for this project, run:',
       );
     });
   });
@@ -258,7 +258,7 @@ describe('redirect(redirectAdapter)', () => {
       });
 
       expect(() => redirectToSignUp({ returnBackUrl })).toThrowError(
-        '@clerk/backend: Missing publishableKey. You can get your key at https://dashboard.clerk.com/last-active?path=api-keys.',
+        '@clerk/backend: Missing publishableKey. To set up Clerk for this project, run:',
       );
     });
 

packages/backend/src/tokens/authStatus.ts

@@ -291,6 +291,8 @@ type BootstrapSignedOutParams = {
  * `isSatellite` / `domain` / `proxyUrl` are carried through so that cross-origin
  * satellite redirects produced by `createRedirect` include the `__clerk_status=needs-sync`
  * marker required for the return-trip handshake.
+ *
+ * @deprecated No longer used by `@clerk/nextjs`; kept for older published SDK versions. Remove in the next major.
  */
 export function createBootstrapSignedOutState({
   signInUrl = '',

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,12 +1,12 @@
 'use client';
 import { InternalClerkProvider as ReactClerkProvider, type Ui } from '@clerk/react/internal';
 import { InitialStateProvider } from '@clerk/shared/react';
-import dynamic from 'next/dynamic';
 import { useRouter } from 'next/navigation';
 import React from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
 import { ClerkNextOptionsProvider, useClerkNextOptions } from '../../client-boundary/NextOptionsContext';
+import { keylessMissingEnvVars } from '../../server/errors';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -16,14 +16,6 @@ import { ClerkScripts } from './ClerkScripts';
 import { useAwaitablePush } from './useAwaitablePush';
 import { useAwaitableReplace } from './useAwaitableReplace';
 
-/**
- * LazyCreateKeylessApplication should only be loaded if the conditions below are met.
- * Note: Using lazy() with Suspense instead of dynamic is not possible as React will throw a hydration error when `ClerkProvider` wraps `<html><body>...`
- */
-const LazyCreateKeylessApplication = dynamic(() =>
-  import('./keyless-creator-reader.js').then(m => m.KeylessCreatorOrReader),
-);
-
 const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderProps<TUi>) => {
   const { __internal_invokeMiddlewareOnAuthStateChange = true, __internal_scriptsSlot, children } = props;
   const router = useRouter();
@@ -115,9 +107,5 @@ export const ClientClerkProvider = <TUi extends Ui = Ui>(
     return <NextClientClerkProvider {...rest}>{children}</NextClientClerkProvider>;
   }
 
-  return (
-    <LazyCreateKeylessApplication>
-      <NextClientClerkProvider {...rest}>{children}</NextClientClerkProvider>
-    </LazyCreateKeylessApplication>
-  );
+  throw new Error(keylessMissingEnvVars);
 };

packages/nextjs/src/app-router/keyless-actions.ts

@@ -1,93 +1,8 @@
 'use server';
-import type { AccountlessApplication } from '@clerk/backend';
-import { cookies, headers } from 'next/headers';
-import { redirect, RedirectType } from 'next/navigation';
 
-import { errorThrower } from '../server/errorThrower';
-import { detectClerkMiddleware } from '../server/headers-utils';
-import { getKeylessCookieName, getKeylessCookieValue } from '../server/keyless';
-import { clerkDevelopmentCache, createKeylessModeMessage } from '../server/keyless-log-cache';
 import { keyless } from '../server/keyless-node';
 import { canUseKeyless } from '../utils/feature-flags';
 
-type SetCookieOptions = Parameters<Awaited<ReturnType<typeof cookies>>['set']>[2];
-
-const keylessCookieConfig = {
-  secure: false,
-  httpOnly: false,
-  sameSite: 'lax',
-} satisfies SetCookieOptions;
-
-export async function syncKeylessConfigAction(args: AccountlessApplication & { returnUrl: string }): Promise<void> {
-  const { claimUrl, publishableKey, secretKey, returnUrl } = args;
-  const cookieStore = await cookies();
-  const request = new Request('https://placeholder.com', { headers: await headers() });
-
-  const keylessCookie = await getKeylessCookieValue(name => cookieStore.get(name)?.value);
-  const pksMatch = keylessCookie?.publishableKey === publishableKey;
-  const sksMatch = keylessCookie?.secretKey === secretKey;
-  if (pksMatch && sksMatch) {
-    // Return early, syncing in not needed.
-    return;
-  }
-
-  // Set the new keys in the cookie.
-  cookieStore.set(
-    await getKeylessCookieName(),
-    JSON.stringify({ claimUrl, publishableKey, secretKey }),
-    keylessCookieConfig,
-  );
-
-  // Request works at runtime since detectClerkMiddleware checks for Request via isRequestWebAPI
-  if (detectClerkMiddleware(request as Parameters<typeof detectClerkMiddleware>[0])) {
-    /**
-     * Force middleware to execute to read the new keys from the cookies and populate the authentication state correctly.
-     */
-    redirect(`/clerk-sync-keyless?returnUrl=${returnUrl}`, RedirectType.replace);
-  }
-
-  return;
-}
-
-export async function createOrReadKeylessAction(): Promise<null | Omit<AccountlessApplication, 'secretKey'>> {
-  if (!canUseKeyless) {
-    return null;
-  }
-
-  let result;
-  try {
-    result = await keyless().getOrCreateKeys();
-  } catch {
-    result = null;
-  }
-
-  if (!result) {
-    errorThrower.throwMissingPublishableKeyError();
-    return null;
-  }
-
-  /**
-   * Notify developers.
-   */
-  clerkDevelopmentCache?.log({
-    cacheKey: result.publishableKey,
-    msg: createKeylessModeMessage(result),
-  });
-
-  const { claimUrl, publishableKey, secretKey, apiKeysUrl } = result;
-  void (await cookies()).set(
-    await getKeylessCookieName(),
-    JSON.stringify({ claimUrl, publishableKey, secretKey }),
-    keylessCookieConfig,
-  );
-
-  return {
-    claimUrl,
-    publishableKey,
-    apiKeysUrl,
-  };
-}
-
 export async function deleteKeylessAction() {
   if (!canUseKeyless) {
     return;