convex 1.41.0 → 1.42.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.41.0",
+  "version": "1.42.1",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -171,7 +171,7 @@
   "dependencies": {
     "esbuild": "0.27.0",
     "prettier": "^3.0.0",
-    "ws": "8.20.1"
+    "ws": "8.21.0"
   },
   "peerDependencies": {
     "@auth0/auth0-react": "^2.0.1",
@@ -266,13 +266,13 @@
     "serve-handler": "~6.1.6",
     "shx": "~0.4.0",
     "skott": "~0.35.4",
-    "tar": "^7.5.11",
+    "tar": "^7.5.16",
     "tsx": "^4.19.4",
     "typedoc": "^0.24.6",
     "typescript": "~5.0.3",
     "typescript-eslint": "~8.57.0",
     "vitest": "^4.1.0",
-    "undici": "7.24.0",
+    "undici": "7.28.0",
     "wait-for-expect": "~4.0.0",
     "zod": "^3.24.0",
     "zod-to-json-schema": "^3.24.0"

package/src/browser/sync/authentication_manager.ts

@@ -36,16 +36,19 @@ type AuthConfig = {
 };
 
 /**
- * In general we take 3 steps:
- *   1. Fetch a possibly cached token
+ * By default we take 3 steps:
+ *   1. Fetch a possibly cached token and send it to the server
  *   2. Immediately fetch a fresh token without using a cache
  *   3. Repeat step 2 before the end of the fresh token's lifetime
  *
- * When we fetch without using a cache we know when the token
- * will expire, and can schedule refetching it.
+ * When `initialAuthTokenReuse` is enabled, step 2 is skipped: the
+ * cached token is reused and a refetch is scheduled based on its
+ * remaining lifetime (estimated via the server's clock skew). This
+ * avoids a second Authenticate message that would cause the server
+ * to re-execute all authenticated queries.
  *
- * If we get an error before a scheduled refetch, we go back
- * to step 2.
+ * If the server rejects a token before a scheduled refetch, we
+ * immediately fetch a fresh token and retry.
  */
 type AuthState =
   | { state: "noAuth" }
@@ -97,6 +100,7 @@ export class AuthenticationManager {
   private readonly clearAuth: () => void;
   private readonly logger: Logger;
   private readonly refreshTokenLeewaySeconds: number;
+  private readonly initialAuthTokenReuse: boolean;
   // Track last value to avoid redundant calls
   private lastRefreshChange: boolean;
   // Number of times we have attempted to confirm the latest token. We retry up
@@ -115,6 +119,7 @@ export class AuthenticationManager {
     config: {
       refreshTokenLeewaySeconds: number;
       logger: Logger;
+      initialAuthTokenReuse: boolean;
     },
   ) {
     this.syncState = syncState;
@@ -126,6 +131,7 @@ export class AuthenticationManager {
     this.clearAuth = callbacks.clearAuth;
     this.logger = config.logger;
     this.refreshTokenLeewaySeconds = config.refreshTokenLeewaySeconds;
+    this.initialAuthTokenReuse = config.initialAuthTokenReuse;
     this.lastRefreshChange = false;
   }
 
@@ -206,7 +212,12 @@ export class AuthenticationManager {
 
     if (this.authState.state === "waitingForServerConfirmationOfCachedToken") {
       this._logVerbose("server confirmed auth token is valid");
-      void this.refetchToken();
+      const cachedToken = this.syncState.getAuth()?.value;
+      if (this.initialAuthTokenReuse && cachedToken) {
+        this.scheduleTokenRefetch(cachedToken, serverMessage.clientClockSkew);
+      } else {
+        void this.refetchToken();
+      }
       this.authState.config.onAuthChange(true);
       return;
     }
@@ -361,7 +372,7 @@ export class AuthenticationManager {
     this.tryRestartSocket();
   }
 
-  private scheduleTokenRefetch(token: string) {
+  private scheduleTokenRefetch(token: string, clientClockSkewMs?: number) {
     if (this.authState.state === "noAuth") {
       return;
     }
@@ -384,17 +395,34 @@ export class AuthenticationManager {
       );
       return;
     }
-    // Because the client and server clocks may be out of sync,
-    // we only know that the token will expire after `exp - iat`,
-    // and since we just fetched a fresh one we know when that
-    // will happen.
-    const tokenValiditySeconds = exp - iat;
-    if (tokenValiditySeconds <= 2) {
+    const fullLifetimeSeconds = exp - iat;
+    if (fullLifetimeSeconds <= 2) {
       this.logger.error(
         "Auth token does not live long enough, cannot refetch the token",
       );
       return;
     }
+    let tokenValiditySeconds: number;
+    if (clientClockSkewMs !== undefined) {
+      // For cached tokens we use the server's clock skew estimate to
+      // compute remaining lifetime. The server computes
+      // clientClockSkew = clientTs - serverReceiveTs, so it's positive
+      // when the client is ahead and negative when behind. To recover
+      // server time: serverNow = Date.now() - clientClockSkew.
+      // Both Date.now() and setTimeout use the same client clock, so
+      // the scheduled delay is accurate regardless of absolute offset.
+      // Connect latency inflates the skew toward "client behind," which
+      // is conservative — we schedule the refetch slightly early.
+      const estimatedServerNowSeconds = (Date.now() - clientClockSkewMs) / 1000;
+      tokenValiditySeconds = exp - estimatedServerNowSeconds;
+      if (tokenValiditySeconds <= 0) {
+        tokenValiditySeconds = 0;
+      }
+    } else {
+      // For freshly-fetched tokens, `exp - iat` is the full lifetime
+      // starting from now.
+      tokenValiditySeconds = fullLifetimeSeconds;
+    }
     // Attempt to refresh the token `refreshTokenLeewaySeconds` before it expires,
     // or immediately if the token is already expiring soon.
     let delay = Math.min(

package/src/browser/sync/client.ts

@@ -137,6 +137,22 @@ export interface BaseConvexClientOptions {
    * Defaults to false, not waiting for an auth token.
    */
   expectAuth?: boolean;
+  /**
+   * This API is experimental: it may change or disappear.
+   *
+   * When true, the client reuses the initial cached auth token instead
+   * of immediately fetching a fresh one. This avoids a second
+   * Authenticate message that causes the server to re-execute all
+   * authenticated queries.
+   *
+   * The cached token's remaining lifetime is estimated using the
+   * server's clock skew measurement, and a refresh is scheduled
+   * before it expires.
+   *
+   * Defaults to false, preserving the original behavior of immediately
+   * fetching a fresh token after the cached token is confirmed.
+   */
+  initialAuthTokenReuse?: boolean;
 }
 
 /**
@@ -358,6 +374,7 @@ export class BaseConvexClient {
       {
         logger: this.logger,
         refreshTokenLeewaySeconds: authRefreshTokenLeewaySeconds,
+        initialAuthTokenReuse: options.initialAuthTokenReuse ?? false,
       },
     );
     this.optimisticQueryResults = new OptimisticQueryResults();

package/src/cli/env.ts

@@ -164,18 +164,25 @@ const envRemoveCmd = new Command("remove")
   });
 
 const envListCmd = new Command("list")
-  .summary("List all variables and their values")
+  .summary("List all environment variables and their values")
   .description(
     [
-      "• List all variables: `npx convex env list`",
+      "• List all variables and their values: `npx convex env list`",
+      "• List only variable names (no values): `npx convex env list --names-only`",
       "• Save all variables to a file: `npx convex env list > .env.convex`",
       "• Append to a file: `npx convex env list >> .env.convex`",
     ].join("\n"),
   )
+  .option(
+    "--names-only",
+    "List only the names of environment variables, without their values",
+  )
   .configureHelp({ showGlobalOptions: true })
   .allowExcessArguments(false)
-  .action(async (_options, cmd) => {
-    const options = cmd.optsWithGlobals();
+  .action(async (cmdOptions, cmd) => {
+    // Note: We use `as` here because optsWithGlobals() type inference doesn't
+    // include global options from the parent command (added via addDeploymentSelectionOptions)
+    const options = cmd.optsWithGlobals() as DeploymentSelectionOptions;
     const { ctx, deployment } = await selectEnvDeployment(options);
     await ensureHasConvexDependency(ctx, "env list");
     await withRunningBackend({
@@ -183,7 +190,9 @@ const envListCmd = new Command("list")
       deployment,
       action: async () => {
         const backend = deploymentEnvBackend(ctx, deployment);
-        await envList(ctx, backend);
+        await envList(ctx, backend, {
+          namesOnly: cmdOptions.namesOnly ?? false,
+        });
       },
     });
   });
@@ -198,7 +207,8 @@ export const env = new Command("env")
       "• Set interactively: `npx convex env set NAME`",
       "• Set multiple from file: `npx convex env set --from-file .env`",
       "• Unset a variable: `npx convex env remove NAME`",
-      "• List all variables: `npx convex env list`",
+      "• List all variables and their values: `npx convex env list`",
+      "• List only variable names (no values): `npx convex env list --names-only`",
       "• Print a variable's value: `npx convex env get NAME`",
       "",
       "By default, this sets and views variables on your dev deployment.",

package/src/cli/envDefault.ts

@@ -141,24 +141,29 @@ const envDefaultRemove = addEnvDefaultOptions(
 
 const envDefaultList = addEnvDefaultOptions(
   new Command("list")
-    .summary("List all default variables")
+    .summary("List all default environment variables and their values")
     .description(
       [
-        "List all default variables.",
-        "",
-        "• `npx convex env default list`",
+        "• List all default variables and their values: `npx convex env default list`",
+        "• List only default variable names (no values): `npx convex env default list --names-only`",
         "",
         "The deployment type is determined by the current deployment (local maps to dev), or by --type if provided.",
       ].join("\n"),
     )
+    .option(
+      "--names-only",
+      "List only the names of environment variables, without their values",
+    )
     .configureHelp({ showGlobalOptions: true })
     .allowExcessArguments(false),
-).action(async (_options, cmd) => {
+).action(async (cmdOptions, cmd) => {
   const options = cmd.optsWithGlobals() as DeploymentSelectionOptions &
     EnvDefaultExtraOptions;
   const { ctx, backend } = await resolveEnvDefaultBackend(options);
   await ensureHasConvexDependency(ctx, "env default list");
-  await envList(ctx, backend);
+  await envList(ctx, backend, {
+    namesOnly: cmdOptions.namesOnly ?? false,
+  });
 });
 
 export const envDefault = new Command("default")
@@ -171,7 +176,8 @@ export const envDefault = new Command("default")
       "",
       "• Set a default variable: `npx convex env default set NAME 'value'`",
       "• Unset a default variable: `npx convex env default remove NAME`",
-      "• List all default variables: `npx convex env default list`",
+      "• List all default variables and their values: `npx convex env default list`",
+      "• List only default variable names (no values): `npx convex env default list --names-only`",
       "• Print a default variable's value: `npx convex env default get NAME`",
     ].join("\n"),
   )

package/src/cli/insights.ts

@@ -101,6 +101,7 @@ export const insights = new Command("insights")
   )
   .allowExcessArguments(false)
   .option("--details", "Show recent events for each insight", false)
+  .option("--json", "Output insights as JSON", false)
   .addDeploymentSelectionOptions(actionDescription("Show insights for"))
   .showHelpAfterError()
   .action(async (cmdOptions) => {
@@ -145,6 +146,17 @@ export const insights = new Command("insights")
       "?view=insights",
     );
 
+    if (cmdOptions.json) {
+      logOutput(
+        JSON.stringify(
+          { deploymentName, dashboardUrl, insights: insightsList },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
     if (insightsList.length === 0) {
       logOutput(
         chalk.green(

package/src/cli/lib/env.test.ts

@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import type { Context } from "../../bundler/context.js";
+import { envList, type EnvVar, type EnvVarBackend } from "./env.js";
+
+const logMocks = vi.hoisted(() => ({
+  logFailure: vi.fn(),
+  logFinishedStep: vi.fn(),
+  logMessage: vi.fn(),
+  logOutput: vi.fn(),
+}));
+
+vi.mock("../../bundler/log.js", () => ({
+  logFailure: logMocks.logFailure,
+  logFinishedStep: logMocks.logFinishedStep,
+  logMessage: logMocks.logMessage,
+  logOutput: logMocks.logOutput,
+}));
+
+function fakeBackend(envs: EnvVar[]): EnvVarBackend {
+  return {
+    get() {
+      return Promise.resolve(null);
+    },
+    list() {
+      return Promise.resolve(envs);
+    },
+    update() {
+      return Promise.reject(new Error("Unexpected update"));
+    },
+    notice: "",
+  };
+}
+
+describe("envList", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test("prints only names without values or warnings when namesOnly is true", async () => {
+    await envList(
+      {} as Context,
+      fakeBackend([
+        { name: "PLAIN", value: "plain-value" },
+        { name: "DANGEROUS", value: "secret'value#fragment" },
+      ]),
+      { namesOnly: true },
+    );
+
+    expect(logMocks.logOutput.mock.calls).toEqual([["PLAIN"], ["DANGEROUS"]]);
+    expect(logMocks.logMessage).not.toHaveBeenCalled();
+
+    const emitted = [
+      ...logMocks.logOutput.mock.calls.flat(),
+      ...logMocks.logMessage.mock.calls.flat(),
+    ].join("\n");
+    expect(emitted).not.toContain("plain-value");
+    expect(emitted).not.toContain("secret'value#fragment");
+    expect(emitted).not.toContain("Warning (");
+  });
+});

package/src/cli/lib/env.ts

@@ -171,13 +171,21 @@ export async function envRemove(
   );
 }
 
-export async function envList(ctx: Context, backend: EnvVarBackend) {
+export async function envList(
+  ctx: Context,
+  backend: EnvVarBackend,
+  options?: { namesOnly?: boolean },
+) {
   const envs = await backend.list();
   if (envs.length === 0) {
     logMessage(`No environment variables set${backend.notice}`);
     return;
   }
   for (const { name, value } of envs) {
+    if (options?.namesOnly) {
+      logOutput(name);
+      continue;
+    }
     const { formatted, warning } = formatEnvValueForDotfile(value);
     if (warning) {
       logMessage(`Warning (${name}): ${warning}`);

package/src/cli/lib/login.ts

@@ -5,6 +5,7 @@ import {
   logAndHandleFetchError,
   throwingFetch,
   isWebContainer,
+  typedPlatformClient,
 } from "./utils/utils.js";
 import open from "open";
 import { chalkStderr } from "chalk";
@@ -37,12 +38,6 @@ custom.setHttpOptionsDefaults({
   timeout: parseInt(process.env.OPENID_CLIENT_TIMEOUT || "10000"),
 });
 
-interface AuthorizeArgs {
-  authnToken: string;
-  deviceName: string;
-  anonymousId?: string | undefined;
-}
-
 export async function checkAuthorization(
   ctx: Context,
   acceptOptIns: boolean,
@@ -390,18 +385,23 @@ export async function performLogin(
     });
   }
 
-  const authorizeArgs: AuthorizeArgs = {
-    authnToken: accessToken!,
-    deviceName: deviceName,
-    anonymousId: anonymousId,
-  };
-  const data = await bigBrainAPI({
-    ctx,
-    method: "POST",
-    path: "authorize",
-    data: authorizeArgs,
+  // Exchange the WorkOS access token for a Convex personal access token.
+  ctx._updateBigBrainAuth({
+    accessToken: accessToken!,
+    kind: "accessToken",
+    header: `Bearer ${accessToken!}`,
   });
-  const globalConfig = { accessToken: data.accessToken };
+  const response = await typedPlatformClient(ctx).POST(
+    "/create_personal_access_token",
+    {
+      // `anonymousId` links a prior anonymous session to this account. It's
+      // intentionally absent from the generated platform API types,
+      // so cast to pass it through.
+      body: { name: deviceName, anonymousId } as { name: string },
+    },
+  );
+  const newAccessToken = response.data!.accessToken;
+  const globalConfig = { accessToken: newAccessToken };
   try {
     await modifyGlobalConfig(ctx, globalConfig);
     const path = globalConfigPath();
@@ -416,7 +416,7 @@ export async function performLogin(
   }
 
   logVerbose(`performLogin: updating big brain auth after login`);
-  await updateBigBrainAuthAfterLogin(ctx, data.accessToken);
+  await updateBigBrainAuthAfterLogin(ctx, newAccessToken);
 
   logVerbose(`performLogin: checking opt ins, acceptOptIns: ${acceptOptIns}`);
   // Do opt in to TOS and Privacy Policy stuff

package/src/cli/lib/logs.ts

@@ -5,7 +5,7 @@ import { nextBackoff } from "./dev.js";
 import chalk, { chalkStderr } from "chalk";
 import { stripVTControlCharacters } from "node:util";
 import { format } from "node:util";
-import { deploymentFetch } from "./utils/utils.js";
+import { deploymentFetch, ThrowingFetchError } from "./utils/utils.js";
 import { FunctionExecution } from "./apiTypes.js";
 
 export type LogMode = "always" | "pause-on-deploy" | "disable";
@@ -122,7 +122,12 @@ export async function watchLogs(
           options?.jsonl,
         );
       }
-    } catch {
+    } catch (e) {
+      // A 403 means the admin key isn't authorized for this deployment.
+      // Retrying won't help, so surface the error and fail immediately.
+      if (e instanceof ThrowingFetchError && e.response.status === 403) {
+        return await e.handle(ctx);
+      }
       numFailures += 1;
     }
     // Handle backoff

package/src/cli/lib/run.ts

@@ -11,7 +11,11 @@ import {
 import { Value, convexToJson, jsonToConvex } from "../../values/value.js";
 import { Context, OneoffCtx } from "../../bundler/context.js";
 import { logFinishedStep, logMessage, logOutput } from "../../bundler/log.js";
-import { waitForever, waitUntilCalled } from "./utils/utils.js";
+import {
+  permissionDeniedErrorMessage,
+  waitForever,
+  waitUntilCalled,
+} from "./utils/utils.js";
 import JSON5 from "json5";
 import path from "path";
 import { readProjectConfig } from "./config.js";
@@ -59,6 +63,15 @@ export async function runFunctionAndLog(
   } catch (err) {
     const errorMessage = (err as Error).toString().trim();
 
+    const permissionError = permissionDeniedErrorMessage(errorMessage);
+    if (permissionError !== null) {
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "fatal",
+        printedMessage: chalkStderr.red(permissionError),
+      });
+    }
+
     if (errorMessage.includes("Could not find function")) {
       const functions = (await runSystemQuery(ctx, {
         deploymentUrl: args.deploymentUrl,
@@ -377,7 +390,7 @@ export async function subscribeAndLog(
 }
 
 export async function subscribe(
-  _ctx: Context,
+  ctx: Context,
   args: {
     deploymentUrl: string;
     adminKey: string;
@@ -399,7 +412,28 @@ export async function subscribe(
     args.deploymentUrl,
     (updatedQueries) => {
       for (const queryToken of updatedQueries) {
-        args.callbacks?.onChange?.(client.localQueryResultByToken(queryToken)!);
+        let result: Value;
+        try {
+          result = client.localQueryResultByToken(queryToken)!;
+        } catch (err) {
+          // A failed query (e.g. a permission error) throws here. Surface
+          // permission errors cleanly instead of an uncaught stack trace, and
+          // let any other error propagate as before.
+          const permissionError = permissionDeniedErrorMessage(
+            (err as Error).toString(),
+          );
+          if (permissionError !== null) {
+            void ctx.crash({
+              exitCode: 1,
+              errorType: "fatal",
+              printedMessage: chalkStderr.red(permissionError),
+            });
+            return;
+          }
+          // eslint-disable-next-line no-restricted-syntax
+          throw err;
+        }
+        args.callbacks?.onChange?.(result);
       }
     },
     {

package/src/cli/lib/typecheck.ts

@@ -139,18 +139,34 @@ async function runTsc(
   tscArgs: string[],
   handleResult: TypecheckResultHandler,
 ): Promise<void> {
-  // Check if tsc is even installed
-  const tscPath =
-    typescriptCompiler === "tsgo"
-      ? path.join(
+  // Check if the TypeScript compiler is even installed
+  let compilerPath: string | undefined;
+  switch (typescriptCompiler) {
+    case "tsgo": {
+      // @typescript/native-preview@7.0.0-dev.20260626.1 switched to using `bin/tsgo` instead of `bin/tsgo.js`.
+      const tsgoPaths = ["tsgo", "tsgo.js"].map((filename) =>
+        path.join(
           "node_modules",
           "@typescript",
           "native-preview",
           "bin",
-          "tsgo.js",
-        )
-      : path.join("node_modules", "typescript", "bin", "tsc");
-  if (!ctx.fs.exists(tscPath)) {
+          filename,
+        ),
+      );
+      compilerPath = tsgoPaths.find((path) => ctx.fs.exists(path));
+      break;
+    }
+    case "tsc": {
+      const tscPath = path.join("node_modules", "typescript", "bin", "tsc");
+      if (ctx.fs.exists(tscPath)) {
+        compilerPath = tscPath;
+      }
+      break;
+    }
+    default:
+      typescriptCompiler satisfies never;
+  }
+  if (!compilerPath) {
     return handleResult("cantTypeCheck", () => {
       logError(
         chalkStderr.gray(
@@ -162,14 +178,14 @@ async function runTsc(
 
   // Check the TypeScript version matches the recommendation from Convex
   const versionResult = await spawnAsync(ctx, process.execPath, [
-    tscPath,
+    compilerPath,
     "--version",
   ]);
 
   const version = versionResult.stdout.match(/Version (.*)/)?.[1] ?? null;
   const hasOlderTypeScriptVersion = version && semver.lt(version, "4.8.4");
 
-  await runTscInner(ctx, tscPath, tscArgs, handleResult);
+  await runTscInner(ctx, compilerPath, tscArgs, handleResult);
 
   // Print this warning after any logs from running `tsc`
   if (hasOlderTypeScriptVersion) {

package/src/cli/lib/utils/utils.ts

@@ -101,6 +101,52 @@ export function readDeployKeyFromEnv(
   return fromDeployKey || fromToken || undefined;
 }
 
+// The prefix the backend's `require_operation` checks use when an identity
+// lacks a permission. The full message names the missing permission, e.g.
+// `You do not have permission to perform this operation (deployment:data:view).`
+const PERMISSION_DENIED_MESSAGE_PREFIX =
+  "You do not have permission to perform this operation";
+
+function deployKeyPermissionAdvice(): string | null {
+  // Name whichever env var is actually set. `CONVEX_DEPLOY_KEY` takes
+  // precedence over `CONVEX_DEPLOYMENT_TOKEN` when both are present.
+  const envVarName = process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
+    ? CONVEX_DEPLOY_KEY_ENV_VAR_NAME
+    : process.env[CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME]
+      ? CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME
+      : null;
+  if (envVarName === null) {
+    return null;
+  }
+  return `This is determined by the permissions granted to ${envVarName}.`;
+}
+
+/**
+ * Detects a server-side authorization failure (a `require_operation` error,
+ * surfaced both as an HTTP 403 and as an error from a system UDF query) and
+ * produces a clean, single-line message naming the missing permission. When a
+ * deploy key is in use, appends advice for configuring its permissions.
+ *
+ * Returns `null` if `errorMessage` is not a permission error, so callers can
+ * fall back to their normal error handling.
+ */
+export function permissionDeniedErrorMessage(
+  errorMessage: string,
+): string | null {
+  const index = errorMessage.indexOf(PERMISSION_DENIED_MESSAGE_PREFIX);
+  if (index === -1) {
+    return null;
+  }
+  // Drop any wrapping context (e.g. the `[CONVEX Q(...)]` prefix) and stack
+  // trace, keeping just the permission sentence.
+  let msg = errorMessage.slice(index).split("\n")[0].trim();
+  const advice = deployKeyPermissionAdvice();
+  if (advice) {
+    msg = `${msg}\n${advice}`;
+  }
+  return msg;
+}
+
 export function parsePositiveInteger(value: string) {
   const parsedValue = parseInteger(value);
   if (parsedValue <= 0) {
@@ -177,6 +223,16 @@ export class ThrowingFetchError extends Error {
     } else if (this.response.status === 401) {
       error_type = "fatal";
       msg = `${msg}\nAuthenticate with \`npx convex dev\``;
+    } else if (this.response.status === 403) {
+      error_type = "fatal";
+      // Surface the missing permission cleanly (e.g. the server includes the
+      // required action like `deployment:data:view`) instead of the noisy
+      // "Error fetching ..." wrapper.
+      msg = this.serverErrorData?.message ?? msg;
+      const advice = deployKeyPermissionAdvice();
+      if (advice) {
+        msg = `${msg}\n${advice}`;
+      }
     } else if (this.response.status === 404) {
       error_type = "fatal";
       msg = `${msg}: ${this.response.url}`;