fix(dashboard): validate display types against all datasets (#577)

Fixes #535. Fixes #536. Supersedes the incorrect fixes in #570 (merged)
and #571 (closed).

## What was wrong

The CLI accepted any `--display` + `--dataset` combination and silently
saved broken widgets. Three independent issues:

1. **Column default too broad** (#536, partially fixed in #570) —
`columns: ["issue"]` was applied for all issue dataset display types,
not just `table`. A `--display line --dataset issue` chart got wrong
columns.

2. **Issue display type validation** (#535) — only `table/area/line/bar`
are valid for the issue dataset but any display type was accepted.

3. **No validation for any other dataset** — `--display table --dataset
tracemetrics` (not supported), `--display table --dataset
preprod-app-size` (not supported), `--display details --dataset logs`
(spans-only), all silently created broken widgets.

## Source of truth

All constraints sourced from Sentry's frontend dataset configs at commit
[`a42668e`](https://github.com/getsentry/sentry/blob/a42668e/static/app/views/dashboards/datasetConfig/):

| Dataset | Supported display types |
|---|---|
| `issue` | `table`, `area`, `line`, `bar` |
| `spans` | `area`, `bar`, `big_number`, `categorical_bar`, `line`,
`stacked_area`, `table`, `top_n`, `details`, `server_tree` |
| `error-events` / `transaction-like` / `metrics` / `logs` / `discover`
| `area`, `bar`, `big_number`, `categorical_bar`, `line`,
`stacked_area`, `table`, `top_n` |
| `tracemetrics` | `area`, `bar`, `big_number`, `categorical_bar`,
`line` |
| `preprod-app-size` | `line` |

## What this does

- Replaces `ISSUE_DATASET_DISPLAY_TYPES` with
`DATASET_SUPPORTED_DISPLAY_TYPES` — a full map for all 9 widget types
- `validateWidgetEnums` does one lookup into the map instead of a
hardcoded issue check
- Column default remains scoped to `issue + table` only

## Test plan

All existing tests pass plus new coverage for:
- `preprod-app-size + table` → error; `+ line` → ok
- `tracemetrics + table` → error
- `spans + details` → ok; `logs + details` → error

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

src/commands/dashboard/resolve.ts

@@ -17,6 +17,7 @@ import { resolveOrg } from "../../lib/resolve-target.js";
 import { setOrgProjectContext } from "../../lib/telemetry.js";
 import { isAllDigits } from "../../lib/utils.js";
 import {
+  DATASET_SUPPORTED_DISPLAY_TYPES,
   type DashboardWidget,
   DISPLAY_TYPES,
   parseAggregate,
@@ -25,6 +26,7 @@ import {
   prepareWidgetQueries,
   validateAggregateNames,
   WIDGET_TYPES,
+  type WidgetType,
 } from "../../types/dashboard.js";
 
 /** Shared widget query flags used by `add` and `edit` commands */
@@ -325,10 +327,11 @@ export function buildWidgetFromFlags(opts: {
   const aggregates = (opts.query ?? ["count"]).map(parseAggregate);
   validateAggregateNames(aggregates, opts.dataset);
 
-  // The issue dataset requires at least one column (group-by) to produce a
-  // visible table — without it, the Sentry UI shows "Columns: None".
-  // Default to ["issue"] so a bare `--dataset issue --display table` just works.
-  const columns = opts.groupBy ?? (opts.dataset === "issue" ? ["issue"] : []);
+  // Issue table widgets need at least one column or the Sentry UI shows "Columns: None".
+  // Default to ["issue"] for table display only — timeseries (line/area/bar) don't use columns.
+  const columns =
+    opts.groupBy ??
+    (opts.dataset === "issue" && opts.display === "table" ? ["issue"] : []);
   // Auto-default orderby to first aggregate descending when group-by is used.
   // Without this, chart widgets (line/area/bar) with group-by + limit error
   // because the dashboard can't determine which top N groups to display.
@@ -380,4 +383,20 @@ export function validateWidgetEnums(display?: string, dataset?: string): void {
       "dataset"
     );
   }
+  if (display && dataset) {
+    // Untracked display types (text, wheel, rage_and_dead_clicks, agents_traces_table)
+    // bypass Sentry's dataset query system entirely — no dataset constraint applies.
+    const isTrackedDisplay = Object.values(
+      DATASET_SUPPORTED_DISPLAY_TYPES
+    ).some((types) => (types as readonly string[]).includes(display));
+    if (isTrackedDisplay) {
+      const supported = DATASET_SUPPORTED_DISPLAY_TYPES[dataset as WidgetType];
+      if (supported && !(supported as readonly string[]).includes(display)) {
+        throw new ValidationError(
+          `The "${dataset}" dataset supports: ${supported.join(", ")}. Got: "${display}".`,
+          "display"
+        );
+      }
+    }
+  }
 }

src/commands/dashboard/widget/edit.ts

@@ -90,9 +90,20 @@ function buildReplacement(
 
   const limit = flags.limit !== undefined ? flags.limit : existing.limit;
 
+  const effectiveDisplay = flags.display ?? existing.displayType;
+  const effectiveDataset = flags.dataset ?? existing.widgetType;
+
+  // Re-validate after merging with existing values. validateWidgetEnums only
+  // checks the cross-constraint when both args are provided, so it misses
+  // e.g. `--dataset preprod-app-size` on a widget that's already `table`.
+  // validateWidgetEnums itself skips untracked display types (text, wheel, etc.).
+  if (flags.display || flags.dataset) {
+    validateWidgetEnums(effectiveDisplay, effectiveDataset);
+  }
+
   const raw: Record<string, unknown> = {
     title: flags["new-title"] ?? existing.title,
-    displayType: flags.display ?? existing.displayType,
+    displayType: effectiveDisplay,
     queries: mergedQueries ?? existing.queries,
     layout: existing.layout,
   };

src/types/dashboard.ts

@@ -299,6 +299,101 @@ export const DiscoverAggregateFunctionSchema = z.enum(
   DISCOVER_AGGREGATE_FUNCTIONS
 );
 
+/**
+ * Valid display types per widget dataset.
+ *
+ * Source: sentry/static/app/views/dashboards/datasetConfig/ @ a42668e87cc8a0b7410ac2acecee6074c52f376f
+ * Each entry mirrors `supportedDisplayTypes` from the corresponding config:
+ *
+ *   issues.tsx         https://github.com/getsentry/sentry/blob/a42668e87cc8a0b7410ac2acecee6074c52f376f/static/app/views/dashboards/datasetConfig/issues.tsx#L90-L95
+ *   spans.tsx          https://github.com/getsentry/sentry/blob/a42668e87cc8a0b7410ac2acecee6074c52f376f/static/app/views/dashboards/datasetConfig/spans.tsx#L287-L297
+ *   errors.tsx         https://github.com/getsentry/sentry/blob/a42668e87cc8a0b7410ac2acecee6074c52f376f/static/app/views/dashboards/datasetConfig/errors.tsx#L115-L123
+ *   transactions.tsx   https://github.com/getsentry/sentry/blob/a42668e87cc8a0b7410ac2acecee6074c52f376f/static/app/views/dashboards/datasetConfig/transactions.tsx#L76-L84
+ *   releases.tsx       https://github.com/getsentry/sentry/blob/a42668e87cc8a0b7410ac2acecee6074c52f376f/static/app/views/dashboards/datasetConfig/releases.tsx#L90-L98
+ *   logs.tsx           https://github.com/getsentry/sentry/blob/a42668e87cc8a0b7410ac2acecee6074c52f376f/static/app/views/dashboards/datasetConfig/logs.tsx#L201-L209
+ *   traceMetrics.tsx   https://github.com/getsentry/sentry/blob/a42668e87cc8a0b7410ac2acecee6074c52f376f/static/app/views/dashboards/datasetConfig/traceMetrics.tsx#L285-L291
+ *   mobileAppSize.tsx  https://github.com/getsentry/sentry/blob/a42668e87cc8a0b7410ac2acecee6074c52f376f/static/app/views/dashboards/datasetConfig/mobileAppSize.tsx#L255
+ *
+ * stacked_area is included for datasets that support timeseries (not in Sentry's UI picker
+ * but accepted by the API and handled by the CLI's query engine).
+ * details and server_tree are spans-only internal display types.
+ *
+ * Four display types are intentionally absent from this map — they bypass Sentry's standard
+ * dataset query system and carry no dataset constraints:
+ *   text                 — renders markdown; no dataset or query involved; user-editable
+ *   wheel                — Web Vitals ring chart; prebuilt dashboards only, not user-editable
+ *   rage_and_dead_clicks — rage/dead click viz; prebuilt only, fetches its own data
+ *   agents_traces_table  — AI agent traces; prebuilt only, fetches its own data
+ * Source: static/app/views/dashboards/utils.tsx (widgetFetchesOwnData / isWidgetEditable)
+ */
+export const DATASET_SUPPORTED_DISPLAY_TYPES = {
+  issue: ["table", "area", "line", "bar"],
+  spans: [
+    "area",
+    "bar",
+    "big_number",
+    "categorical_bar",
+    "line",
+    "stacked_area",
+    "table",
+    "top_n",
+    "details",
+    "server_tree",
+  ],
+  "error-events": [
+    "area",
+    "bar",
+    "big_number",
+    "categorical_bar",
+    "line",
+    "stacked_area",
+    "table",
+    "top_n",
+  ],
+  "transaction-like": [
+    "area",
+    "bar",
+    "big_number",
+    "categorical_bar",
+    "line",
+    "stacked_area",
+    "table",
+    "top_n",
+  ],
+  metrics: [
+    "area",
+    "bar",
+    "big_number",
+    "categorical_bar",
+    "line",
+    "stacked_area",
+    "table",
+    "top_n",
+  ],
+  logs: [
+    "area",
+    "bar",
+    "big_number",
+    "categorical_bar",
+    "line",
+    "stacked_area",
+    "table",
+    "top_n",
+  ],
+  discover: [
+    "area",
+    "bar",
+    "big_number",
+    "categorical_bar",
+    "line",
+    "stacked_area",
+    "table",
+    "top_n",
+  ],
+  tracemetrics: ["area", "bar", "big_number", "categorical_bar", "line"],
+  "preprod-app-size": ["line"],
+} as const satisfies Record<WidgetType, readonly string[]>;
+
 /**
  * Valid `is:` filter values for issue search conditions (--where flag).
  * Only valid when widgetType is "issue". Other datasets don't support `is:`.

test/commands/dashboard/widget/add.test.ts

@@ -212,6 +212,53 @@ describe("dashboard widget add", () => {
     expect(err.message).toContain("Unknown aggregate function");
   });
 
+  test("throws ValidationError for big_number with issue dataset", async () => {
+    const { context } = createMockContext();
+    const func = await addCommand.loader();
+
+    const err = await func
+      .call(
+        context,
+        { json: false, display: "big_number", dataset: "issue" },
+        "123",
+        "Unresolved Count"
+      )
+      .catch((e: Error) => e);
+    expect(err).toBeInstanceOf(ValidationError);
+    expect(err.message).toContain('"issue" dataset supports');
+  });
+
+  test("allows line/area/bar with issue dataset", async () => {
+    const { context } = createMockContext();
+    const func = await addCommand.loader();
+
+    for (const display of ["line", "area", "bar"]) {
+      updateDashboardSpy.mockClear();
+      await func.call(
+        context,
+        { json: false, display, dataset: "issue" },
+        "123",
+        "Issues Over Time"
+      );
+      expect(updateDashboardSpy).toHaveBeenCalledTimes(1);
+    }
+  });
+
+  test("issue line dataset does not default columns", async () => {
+    const { context } = createMockContext();
+    const func = await addCommand.loader();
+    await func.call(
+      context,
+      { json: false, display: "line", dataset: "issue" },
+      "123",
+      "Issues Over Time"
+    );
+
+    const body = updateDashboardSpy.mock.calls[0]?.[2];
+    const addedWidget = body.widgets.at(-1);
+    expect(addedWidget.queries[0].columns).toEqual([]);
+  });
+
   test("issue dataset defaults columns to ['issue'] and orderby to -count()", async () => {
     const { context } = createMockContext();
     const func = await addCommand.loader();
@@ -249,6 +296,81 @@ describe("dashboard widget add", () => {
     expect(addedWidget.queries[0].columns).toEqual(["project"]);
   });
 
+  // preprod-app-size: line only
+  // https://github.com/getsentry/sentry/blob/a42668e/static/app/views/dashboards/datasetConfig/mobileAppSize.tsx#L255
+  test("throws ValidationError for table with preprod-app-size dataset", async () => {
+    const { context } = createMockContext();
+    const func = await addCommand.loader();
+    const err = await func
+      .call(
+        context,
+        { json: false, display: "table", dataset: "preprod-app-size" },
+        "123",
+        "App Size"
+      )
+      .catch((e: Error) => e);
+    expect(err).toBeInstanceOf(ValidationError);
+    expect(err.message).toContain('"preprod-app-size" dataset supports');
+  });
+
+  test("allows line with preprod-app-size dataset", async () => {
+    const { context } = createMockContext();
+    const func = await addCommand.loader();
+    await func.call(
+      context,
+      { json: false, display: "line", dataset: "preprod-app-size" },
+      "123",
+      "App Size"
+    );
+    expect(updateDashboardSpy).toHaveBeenCalledTimes(1);
+  });
+
+  // tracemetrics: no table or top_n
+  // https://github.com/getsentry/sentry/blob/a42668e/static/app/views/dashboards/datasetConfig/traceMetrics.tsx#L285-L291
+  test("throws ValidationError for table with tracemetrics dataset", async () => {
+    const { context } = createMockContext();
+    const func = await addCommand.loader();
+    const err = await func
+      .call(
+        context,
+        { json: false, display: "table", dataset: "tracemetrics" },
+        "123",
+        "Trace Metrics"
+      )
+      .catch((e: Error) => e);
+    expect(err).toBeInstanceOf(ValidationError);
+    expect(err.message).toContain('"tracemetrics" dataset supports');
+  });
+
+  // spans: only dataset supporting details and server_tree
+  // https://github.com/getsentry/sentry/blob/a42668e/static/app/views/dashboards/datasetConfig/spans.tsx#L287-L297
+  test("allows details display with spans dataset", async () => {
+    const { context } = createMockContext();
+    const func = await addCommand.loader();
+    await func.call(
+      context,
+      { json: false, display: "details", dataset: "spans" },
+      "123",
+      "Span Details"
+    );
+    expect(updateDashboardSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test("throws ValidationError for details display with non-spans dataset", async () => {
+    const { context } = createMockContext();
+    const func = await addCommand.loader();
+    const err = await func
+      .call(
+        context,
+        { json: false, display: "details", dataset: "logs" },
+        "123",
+        "Details"
+      )
+      .catch((e: Error) => e);
+    expect(err).toBeInstanceOf(ValidationError);
+    expect(err.message).toContain('"logs" dataset supports');
+  });
+
   test("auto-defaults orderby when group-by + limit provided", async () => {
     const { context } = createMockContext();
     const func = await addCommand.loader();