fix(errors): surface user search-query 400s as ValidationError, keep CLI-built 400s reported (CLI-FA)

src/commands/event/list.ts

@@ -15,7 +15,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
-import { ContextError } from "../../lib/errors.js";
+import { ContextError, toSearchQueryError } from "../../lib/errors.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { buildListCommand, paginationHint } from "../../lib/list-command.js";
 import { withProgress } from "../../lib/polling.js";
@@ -155,6 +155,9 @@ export const listCommand = buildListCommand("event", {
           full: flags.full,
           cursor,
           ...timeRangeToApiParams(timeRange),
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );
 

src/commands/explore.ts

@@ -20,7 +20,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../lib/db/pagination.js";
-import { ValidationError } from "../lib/errors.js";
+import { toSearchQueryError, ValidationError } from "../lib/errors.js";
 import { filterFields } from "../lib/formatters/json.js";
 import { buildMetaColumns } from "../lib/formatters/meta-table.js";
 import { CommandOutput } from "../lib/formatters/output.js";
@@ -792,7 +792,13 @@ export const exploreCommand = buildListCommand("explore", {
         message: `Querying ${dataset} in ${project ? `${org}/${project}` : org}...`,
         json: flags.json,
       },
-      () => config.fetch({ cursor, limit: flags.limit, timeRange })
+      () =>
+        config
+          .fetch({ cursor, limit: flags.limit, timeRange })
+          .catch((error: unknown): never => {
+            // An unparseable user --query is a user input mistake, not a CLI bug.
+            throw toSearchQueryError(error, flags.query);
+          })
     );
 
     advancePaginationState(PAGINATION_KEY, contextKey, direction, nextCursor);

src/commands/issue/events.ts

@@ -12,7 +12,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
-import { ContextError } from "../../lib/errors.js";
+import { ContextError, toSearchQueryError } from "../../lib/errors.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { buildListCommand, paginationHint } from "../../lib/list-command.js";
 import { withProgress } from "../../lib/polling.js";
@@ -137,6 +137,9 @@ export const eventsCommand = buildListCommand("issue", {
           full: flags.full,
           cursor,
           ...timeRangeToApiParams(timeRange),
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );
 

src/commands/issue/list.ts

@@ -40,6 +40,7 @@
 import {
   ApiError,
   ContextError,
+  toSearchQueryError,
   ValidationError,
   withAuthGuard,
 } from "../../lib/errors.js";
@@ -901,6 +902,13 @@
   error: unknown,
   flags: Pick<ListFlags, "query" | "period" | "sort">
 ): never {
+  // A user-supplied --query the server cannot parse is a user input mistake,
+  // not a CLI bug: surface it as a ValidationError. A 400 with no user --query
+  // (the CLI built a bad query) falls through and stays a reported ApiError.
+  const queryError = toSearchQueryError(error, flags.query);
+  if (queryError !== error) {
+    throw queryError;
+  }
   if (error instanceof ApiError) {
     if (error.status === 400) {
       throw new ApiError(
@@ -1119,6 +1127,14 @@
     const { error: first } = failures[0]!;
     const prefix = `Failed to fetch issues from ${targets.length} project(s)`;
 
+    // A user-supplied --query the server cannot parse is a user input mistake,
+    // not a CLI bug — surface it as a ValidationError before wrapping as a
+    // multi-project ApiError. CLI-authored 400s fall through and stay reported.
+    const queryError = toSearchQueryError(first, flags.query);
+    if (queryError !== first) {
+      throw queryError;
+    }
+
     // Propagate ApiError so telemetry sees the original status code.
     // For 400 errors, append actionable suggestions since the user's query
     // or parameters are likely malformed. Common causes: invalid Sentry

src/commands/log/list.ts

@@ -22,6 +22,7 @@
 import {
   AuthError,
   stringifyUnknown,
+  toSearchQueryError,
   ValidationError,
 } from "../../lib/errors.js";
 import {
@@ -180,6 +181,9 @@
     ...timeRangeToApiParams(timeRange),
     sort: flags.sort,
     extraFields: flags.fields,
+  }).catch((error: unknown): never => {
+    // An unparseable user --query is a user input mistake, not a CLI bug.
+    throw toSearchQueryError(error, flags.query);
   });
 
   const periodLabel =

src/commands/span/list.ts

@@ -20,6 +20,7 @@
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
+import { toSearchQueryError } from "../../lib/errors.js";
 import {
   type FlatSpan,
   formatSpanTable,
@@ -390,6 +391,9 @@
         ...timeRangeToApiParams(timeRange),
         extraFields: extraApiFields,
         allProjects: true,
+      }).catch((error: unknown): never => {
+        // An unparseable user --query is a user input mistake, not a CLI bug.
+        throw toSearchQueryError(error, flags.query);
       })
   );
 

src/commands/trace/list.ts

@@ -13,6 +13,7 @@ import {
   hasPreviousPage,
   resolveCursor,
 } from "../../lib/db/pagination.js";
+import { toSearchQueryError } from "../../lib/errors.js";
 import { formatTraceTable } from "../../lib/formatters/index.js";
 import { filterFields } from "../../lib/formatters/json.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
@@ -289,6 +290,9 @@ export const listCommand = buildListCommand("trace", {
           sort: flags.sort,
           cursor,
           ...timeRangeToApiParams(timeRange),
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );
 

src/commands/trace/logs.ts

@@ -13,6 +13,7 @@ import {
 } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
+import { toSearchQueryError } from "../../lib/errors.js";
 import { filterFields } from "../../lib/formatters/json.js";
 import { formatLogTable } from "../../lib/formatters/log.js";
 import { CommandOutput, formatFooter } from "../../lib/formatters/output.js";
@@ -207,6 +208,9 @@ export const logsCommand = buildCommand({
           limit: flags.limit,
           query,
           sort: flags.sort,
+        }).catch((error: unknown): never => {
+          // An unparseable user --query is a user input mistake, not a CLI bug.
+          throw toSearchQueryError(error, flags.query);
         })
     );
 

src/lib/error-reporting.ts

@@ -28,7 +28,6 @@
   DeviceFlowError,
   HostScopeError,
   isNetworkError,
-  isSearchQueryParseError,
   OutputError,
   ResolutionError,
   SeerError,
@@ -51,7 +50,6 @@
   | "context_missing"
   | "auth_expected"
   | "api_user_error"
-  | "api_query_error"
   | "network_error";
 
 /**
@@ -93,16 +91,13 @@
   }
   if (error instanceof ApiError && error.status > 400 && error.status < 500) {
     return "api_user_error";
   }
-  // A 400 normally signals a malformed request the CLI built (a code defect),
-  // so it is captured by default. The exception: when the server reports it
-  // could not parse the user's search query, the `--query` syntax is wrong
-  // (CLI-FA: ~450 users across issue/explore/trace list). That is a user input
-  // error, and the API already returns an actionable message, so silence it.
-  if (error instanceof ApiError && isSearchQueryParseError(error)) {
-    return "api_query_error";
-  }
+  // A 400 (Bad Request) signals a malformed request the CLI built — a code
+  // defect — so it is always captured. A user's unparseable `--query` is NOT a
+  // 400 here: it is converted to a ValidationError at the command boundary
+  // (toSearchQueryError) so the user gets an actionable message and the bug
+  // signal for CLI-authored bad queries is preserved (CLI-FA).
   return null;
 }
 
 /** Emit a metric for silenced errors so volume remains visible. */

src/lib/errors.ts

@@ -780,6 +780,63 @@
   );
 }
 
+/**
+ * Standard actionable hint shown when a user-supplied search query is rejected.
+ * Exported so command boundaries can reuse it alongside command-specific hints.
+ */
+export const SEARCH_QUERY_HELP =
+  "Check your --query syntax (Sentry search reference: https://docs.sentry.io/concepts/search/)";
+
+/**
+ * Convert a Sentry search-query parse failure into a {@link ValidationError}
+ * when the user actually supplied the query; otherwise return the error
+ * unchanged.
+ *
+ * HTTP 400 means the server rejected our request as malformed, which has two
+ * very different causes that are only distinguishable at the command boundary
+ * (where `flags.query` is in scope):
+ *
+ * - **The user typed an invalid `--query`** — a user input mistake. We surface
+ *   a clean, actionable {@link ValidationError} (correct exit code, no "CLI
+ *   bug" upgrade nudge) instead of a raw "400 Bad Request".
+ * - **The CLI built the query itself** (no user `--query`) — a genuine CLI
+ *   defect. The original {@link ApiError} (status 400) is returned untouched so
+ *   it stays reported to Sentry as the bug it is.
+ *
+ * This is why search-query 400s are no longer special-cased in the error
+ * classifiers (`classifySilenced`, {@link isUserError}, `isUserApiError`):
+ * silencing every "Error parsing search query" 400 also hid the CLI-authored
+ * ones, papering over real bugs.
+ *
+ * @param error - The error thrown by a list/search API call
+ * @param userQuery - The user-supplied search query (`flags.query`), if any
+ * @param extraSuggestions - Optional command-specific hints appended after the
+ *   standard search-syntax help
+ * @returns A {@link ValidationError} for user-query mistakes, else `error`
+ */
+export function toSearchQueryError(
+  error: unknown,
+  userQuery: string | undefined,
+  extraSuggestions: readonly string[] = []
+): unknown {
+  if (
+    userQuery &&
+    error instanceof ApiError &&
+    isSearchQueryParseError(error)
+  ) {
+    const lines: string[] = [];
+    if (error.detail) {
+      lines.push(error.detail, "");
+    }
+    lines.push("Suggestions:");
+    for (const suggestion of [SEARCH_QUERY_HELP, ...extraSuggestions]) {
+      lines.push(`  • ${suggestion}`);
+    }
+    return new ValidationError(lines.join("\n"), "query");
+  }
+  return error;
+}
+
 /**
  * Whether an error is a raw network-level fetch failure — the CLI could not
  * reach the Sentry API at all (offline, DNS failure, connection
@@ -822,14 +879,12 @@
     if (error.status === 0) {
       return true;
     }
-    // 400 usually means the CLI constructed a bad request, so it is treated as
-    // a CLI bug — except when the server reports the user's search query was
-    // unparseable, which is a user input mistake.
-    if (isSearchQueryParseError(error)) {
-      return true;
-    }
+    // 400 means the CLI constructed a bad request, which is a CLI bug — not a
+    // user error. (A user's unparseable `--query` is converted to a
+    // ValidationError at the command boundary via toSearchQueryError, so it
+    // never reaches here as an ApiError.)
     return error.status > 400 && error.status < 500;
   }
 
   if (
     error instanceof AbortError ||

src/lib/telemetry.ts

@@ -37,7 +37,7 @@
   enrichEventWithGroupingTags,
   reportCliError,
 } from "./error-reporting.js";
-import { ApiError, isSearchQueryParseError } from "./errors.js";
+import { ApiError } from "./errors.js";
 import { attachSentryReporter, logger } from "./logger.js";
 import { getSentryBaseUrl, isSentrySaasUrl } from "./sentry-urls.js";
 import { makeCompressedTransport } from "./telemetry/zstd-transport.js";
@@ -347,10 +347,10 @@
  * Check if an error is a user-caused (401–499) API error.
  *
  * 401–499 errors are user errors — wrong issue IDs, no access, rate limited —
- * not CLI bugs. 400 Bad Request is **excluded** because it usually indicates
- * the CLI constructed a malformed API request, which is a code defect — except
- * when the server reports the user's search query was unparseable, which is a
- * user input mistake (kept in sync with `classifySilenced` / `isUserError`).
+ * not CLI bugs. 400 Bad Request is **excluded** because it indicates the CLI
+ * constructed a malformed API request, which is a code defect. (A user's
+ * unparseable `--query` is converted to a ValidationError at the command
+ * boundary via toSearchQueryError, so it never reaches here as an ApiError.)
  *
  * These should be recorded as span attributes for volume-spike detection in
  * Discover, but should NOT be captured as Sentry exceptions.
@@ -361,11 +361,9 @@
   if (!(error instanceof ApiError)) {
     return false;
   }
-  return (
-    isSearchQueryParseError(error) || (error.status > 400 && error.status < 500)
-  );
+  return error.status > 400 && error.status < 500;
 }
 
 /**
  * Record a client API error as span attributes for Discover queryability.
  *