fix(dashboard): reject deprecated datasets at CLI level before API call

Split WIDGET_TYPES into active types and DEPRECATED_WIDGET_TYPES
(discover, transaction-like). The CLI now rejects deprecated datasets
immediately with actionable migration hints instead of letting the
API return a cryptic error.

- WIDGET_TYPES: only active datasets the API accepts for creation
- DEPRECATED_WIDGET_TYPES: discover, transaction-like
- ALL_WIDGET_TYPES: union of both, used for parsing server responses
- validateWidgetEnums: checks deprecated types first with specific hints
- --dataset flag brief now lists valid values inline from WIDGET_TYPES
- DashboardWidgetInputSchema uses WIDGET_TYPES (rejects deprecated)
- DashboardWidgetSchema still accepts ALL_WIDGET_TYPES (server compat)

Author: BYK

plugins/sentry-cli/skills/sentry-cli/references/dashboards.md

@@ -76,7 +76,7 @@ Add a widget to a dashboard
 
 **Flags:**
 - `-d, --display <value> - Display type (big_number, line, area, bar, table, stacked_area, top_n, text, categorical_bar, details, wheel, rage_and_dead_clicks, server_tree, agents_traces_table)`
-- `--dataset <value> - Widget dataset (default: spans). Do NOT use "discover" or "transaction-like" — both are deprecated. Use "spans" with --where "is_transaction:true" to query transactions`
+- `--dataset <value> - Widget dataset: issue, metrics, error-events, spans, logs, tracemetrics, preprod-app-size (default: spans)`
 - `-q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)`
 - `-w, --where <value> - Search conditions filter (e.g. is:unresolved)`
 - `-g, --group-by <value>... - Group-by column (repeatable). Requires --limit`
@@ -121,7 +121,7 @@ Edit a widget in a dashboard
 - `-t, --title <value> - Widget title to match`
 - `--new-title <value> - New widget title`
 - `-d, --display <value> - Display type (big_number, line, area, bar, table, stacked_area, top_n, text, categorical_bar, details, wheel, rage_and_dead_clicks, server_tree, agents_traces_table)`
-- `--dataset <value> - Widget dataset (default: spans)`
+- `--dataset <value> - Widget dataset: issue, metrics, error-events, spans, logs, tracemetrics, preprod-app-size (default: spans)`
 - `-q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)`
 - `-w, --where <value> - Search conditions filter (e.g. is:unresolved)`
 - `-g, --group-by <value>... - Group-by column (repeatable)`

src/commands/dashboard/resolve.ts

@@ -477,9 +477,20 @@ export function enrichDashboardError(
   throw error;
 }
 
+/** Migration hints for deprecated dataset names */
+const DEPRECATED_DATASET_HINTS: Record<string, string> = {
+  discover:
+    'The "discover" dataset is deprecated. Use "error-events" for errors or "spans" for transactions/spans.',
+  "transaction-like":
+    'The "transaction-like" dataset is deprecated. Use "spans" with --where "is_transaction:true" instead.',
+};
+
 /**
  * Validate --display and --dataset flag values against known enums.
  *
+ * Rejects deprecated datasets (`discover`, `transaction-like`) with
+ * actionable migration hints before making any API calls.
+ *
  * @param display - Display type flag value
  * @param dataset - Dataset flag value
  */
@@ -493,14 +504,18 @@ export function validateWidgetEnums(display?: string, dataset?: string): void {
       "display"
     );
   }
-  if (
-    dataset &&
-    !WIDGET_TYPES.includes(dataset as (typeof WIDGET_TYPES)[number])
-  ) {
-    throw new ValidationError(
-      `Invalid --dataset value "${dataset}".\nValid datasets: ${WIDGET_TYPES.join(", ")}`,
-      "dataset"
-    );
+  if (dataset) {
+    // Check for deprecated datasets first — give a specific migration hint
+    const deprecationHint = DEPRECATED_DATASET_HINTS[dataset];
+    if (deprecationHint) {
+      throw new ValidationError(deprecationHint, "dataset");
+    }
+    if (!WIDGET_TYPES.includes(dataset as (typeof WIDGET_TYPES)[number])) {
+      throw new ValidationError(
+        `Invalid --dataset value "${dataset}".\nValid datasets: ${WIDGET_TYPES.join(", ")}`,
+        "dataset"
+      );
+    }
   }
   if (display && dataset) {
     // Untracked display types (text, wheel, rage_and_dead_clicks, agents_traces_table)

src/commands/dashboard/widget/add.ts

@@ -19,6 +19,7 @@ import {
   FALLBACK_LAYOUT,
   prepareDashboardForUpdate,
   validateWidgetLayout,
+  WIDGET_TYPES,
   type WidgetLayoutFlags,
 } from "../../../types/dashboard.js";
 import {
@@ -119,8 +120,7 @@ export const addCommand = buildCommand({
       dataset: {
         kind: "parsed",
         parse: String,
-        brief:
-          'Widget dataset (default: spans). Do NOT use "discover" or "transaction-like" — both are deprecated. Use "spans" with --where "is_transaction:true" to query transactions',
+        brief: `Widget dataset: ${WIDGET_TYPES.join(", ")} (default: spans)`,
         optional: true,
       },
       query: {

src/commands/dashboard/widget/edit.ts

@@ -24,6 +24,7 @@ import {
   prepareWidgetQueries,
   validateAggregateNames,
   validateWidgetLayout,
+  WIDGET_TYPES,
   type WidgetLayoutFlags,
 } from "../../../types/dashboard.js";
 import {
@@ -207,7 +208,7 @@ export const editCommand = buildCommand({
       dataset: {
         kind: "parsed",
         parse: String,
-        brief: "Widget dataset (default: spans)",
+        brief: `Widget dataset: ${WIDGET_TYPES.join(", ")} (default: spans)`,
         optional: true,
       },
       query: {

src/types/dashboard.ts

@@ -19,23 +19,43 @@ import { logger } from "../lib/logger.js";
 // ---------------------------------------------------------------------------
 
 /**
- * Valid widget types (dataset selectors).
+ * Widget types (dataset selectors) the API still accepts for creation.
  *
  * Source: sentry/src/sentry/models/dashboard_widget.py DashboardWidgetTypes.TYPES
  */
 export const WIDGET_TYPES = [
-  "discover",
   "issue",
   "metrics",
   "error-events",
-  "transaction-like",
   "spans",
   "logs",
   "tracemetrics",
   "preprod-app-size",
 ] as const;
 
-export type WidgetType = (typeof WIDGET_TYPES)[number];
+/**
+ * Deprecated widget types rejected by the Sentry Dashboard API.
+ *
+ * - `discover` → use `error-events` for errors or `spans` for everything else
+ * - `transaction-like` → use `spans` with `is_transaction:true` filter
+ */
+export const DEPRECATED_WIDGET_TYPES = [
+  "discover",
+  "transaction-like",
+] as const;
+
+export type DeprecatedWidgetType = (typeof DEPRECATED_WIDGET_TYPES)[number];
+
+/**
+ * All widget types including deprecated — used for parsing server responses
+ * where existing dashboards may still reference old types.
+ */
+export const ALL_WIDGET_TYPES = [
+  ...WIDGET_TYPES,
+  ...DEPRECATED_WIDGET_TYPES,
+] as const;
+
+export type WidgetType = (typeof ALL_WIDGET_TYPES)[number];
 
 /** Default widgetType — the modern spans dataset covers most use cases */
 export const DEFAULT_WIDGET_TYPE: WidgetType = "spans";

test/types/dashboard.test.ts

@@ -8,10 +8,12 @@
 import { describe, expect, test } from "bun:test";
 import { ValidationError } from "../../src/lib/errors.js";
 import {
+  ALL_WIDGET_TYPES,
   assignDefaultLayout,
   type DashboardWidget,
   DashboardWidgetInputSchema,
   DEFAULT_WIDGET_TYPE,
+  DEPRECATED_WIDGET_TYPES,
   DISCOVER_AGGREGATE_FUNCTIONS,
   DISPLAY_TYPES,
   DiscoverAggregateFunctionSchema,
@@ -49,7 +51,13 @@ describe("WIDGET_TYPES", () => {
     expect(DEFAULT_WIDGET_TYPE).toBe("spans");
   });
 
-  test("contains all expected dataset types", () => {
+  test("excludes deprecated types", () => {
+    for (const t of DEPRECATED_WIDGET_TYPES) {
+      expect(WIDGET_TYPES).not.toContain(t);
+    }
+  });
+
+  test("ALL_WIDGET_TYPES includes both active and deprecated", () => {
     const expected: WidgetType[] = [
       "discover",
       "issue",
@@ -62,7 +70,7 @@ describe("WIDGET_TYPES", () => {
       "preprod-app-size",
     ];
     for (const t of expected) {
-      expect(WIDGET_TYPES).toContain(t);
+      expect(ALL_WIDGET_TYPES).toContain(t);
     }
   });
 });