fix: prevent experiments from getting stuck in pending on empty datasets (#14031)

Experiments triggered on datasets with zero items would silently fail,
leaving the experiment record stuck in "pending" status forever. The
fire-and-forget `.catch(() => {})` swallowed the error from
`runExperiment()` before it could update the status.

Three-layer fix:

**Core** — `startExperimentAsync` now validates item count before
creating the experiment record. Throws `EXPERIMENT_NO_ITEMS` on empty
datasets. The catch handler marks experiments as `failed` and logs the
error instead of silently discarding.

**Server** — Maps `EXPERIMENT_NO_ITEMS` to HTTP 400. Returns actual
`totalItems` from experiment instead of hardcoded `0`.

**UI** — Disables the Run Experiment button with a tooltip when dataset
has no items.

Also added test coverage for the empty dataset paths in both
`dataset.test.ts` and `runExperiment.test.ts`.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Triggering an experiment on an empty dataset now errors immediately
(HTTP 400) instead of staying pending.
* Setup failures for async experiments are logged and mark the
experiment as failed.
  * Experiment responses now report an accurate totalItems count.

* **New Features**
* Run Experiment button is disabled for empty datasets with a tooltip:
"Add items to the dataset before running an experiment".
* UI checks the unfiltered dataset so searches won't incorrectly disable
the trigger.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: YJ <yj@example.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-6) <noreply@mastra.ai>

Author: 3 people

.changeset/fix-empty-experiments-core.md

@@ -0,0 +1,6 @@
+---
+'@mastra/core': patch
+'@mastra/server': patch
+---
+
+Experiments now fail immediately with a clear error when triggered on a dataset with zero items, instead of getting stuck in "pending" status forever. The experiment trigger API returns HTTP 400 for empty datasets. Unexpected errors during async experiment setup are now logged and mark the experiment as failed.

.changeset/fix-empty-experiments-ui.md

@@ -0,0 +1,5 @@
+---
+'@mastra/playground-ui': patch
+---
+
+The "Run Experiment" button is now disabled when a dataset has no items, with a tooltip explaining that items must be added first.

packages/core/src/datasets/__tests__/dataset.test.ts

@@ -70,6 +70,7 @@ describe('Dataset', () => {
       getScorerById: vi.fn(),
       getWorkflowById: vi.fn(),
       getWorkflow: vi.fn(),
+      getLogger: vi.fn().mockReturnValue({ error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() }),
     } as unknown as Mastra;
 
     // Create a dataset for tests that need one
@@ -306,6 +307,98 @@ describe('Dataset', () => {
     await new Promise(r => setTimeout(r, 500));
   });
 
+  it('startExperimentAsync throws EXPERIMENT_NO_ITEMS on empty dataset', async () => {
+    await expect(
+      ds.startExperimentAsync({
+        task: async () => 'ok',
+        scorers: [],
+      }),
+    ).rejects.toThrow('has no items');
+
+    try {
+      await ds.startExperimentAsync({ task: async () => 'ok', scorers: [] });
+    } catch (err) {
+      expect(err).toBeInstanceOf(MastraError);
+      expect((err as MastraError).id).toBe('EXPERIMENT_NO_ITEMS');
+    }
+
+    // Verify no experiment record was created
+    const { experiments } = await ds.listExperiments();
+    expect(experiments).toHaveLength(0);
+  });
+
+  it('startExperimentAsync returns totalItems matching dataset item count', async () => {
+    await ds.addItem({ input: { prompt: 'Hello' } });
+    await ds.addItem({ input: { prompt: 'World' } });
+
+    const result = await ds.startExperimentAsync({
+      task: async () => 'ok',
+      scorers: [],
+    });
+
+    expect(result.totalItems).toBe(2);
+
+    // Wait for fire-and-forget to complete
+    await new Promise(r => setTimeout(r, 500));
+  });
+
+  it('startExperimentAsync records the resolved version in experiment record', async () => {
+    // Add two items → dataset version becomes 2
+    await ds.addItem({ input: { prompt: 'A' } });
+    await ds.addItem({ input: { prompt: 'B' } });
+
+    // Run experiment pinned to version 1 (only first item visible)
+    const result = await ds.startExperimentAsync({
+      task: async () => 'ok',
+      scorers: [],
+      version: 1,
+    });
+
+    const experiment = await experimentsStorage.getExperimentById({ id: result.experimentId });
+    expect(experiment).not.toBeNull();
+    expect(experiment!.datasetVersion).toBe(1);
+    expect(result.totalItems).toBe(1);
+
+    // Wait for fire-and-forget to complete
+    await new Promise(r => setTimeout(r, 500));
+  });
+
+  // 23b. startExperimentAsync — throws on empty dataset
+  it('startExperimentAsync throws EXPERIMENT_NO_ITEMS when dataset has no items', async () => {
+    // Dataset has no items — do NOT add any
+    try {
+      await ds.startExperimentAsync({
+        task: async () => 'ok',
+        scorers: [],
+      });
+      expect.fail('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(MastraError);
+      expect((err as MastraError).id).toBe('EXPERIMENT_NO_ITEMS');
+    }
+
+    // Verify no experiment record was created
+    const result = await experimentsStorage.listExperiments({
+      datasetId,
+      pagination: { page: 0, perPage: 10 },
+    });
+    expect(result.experiments.length).toBe(0);
+  });
+
+  // 23c. startExperiment — throws on empty dataset (sync path)
+  it('startExperiment throws on empty dataset', async () => {
+    try {
+      await ds.startExperiment({
+        task: async () => 'ok',
+        scorers: [],
+      });
+      expect.fail('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(MastraError);
+      expect((err as MastraError).id).toBe('EXPERIMENT_NO_ITEMS');
+    }
+  });
+
   // 24. listExperiments
   it('listExperiments returns runs for this dataset', async () => {
     await ds.addItem({ input: { prompt: 'Hello' } });

packages/core/src/datasets/dataset.ts

@@ -289,7 +289,7 @@ export class Dataset {
    */
   async startExperimentAsync<I = unknown, O = unknown, E = unknown>(
     config: StartExperimentConfig<I, O, E>,
-  ): Promise<{ experimentId: string; status: 'pending' }> {
+  ): Promise<{ experimentId: string; status: 'pending'; totalItems: number }> {
     const experimentsStore = await this.#getExperimentsStore();
     const datasetsStore = await this.#getDatasetsStore();
 
@@ -303,27 +303,51 @@ export class Dataset {
       });
     }
 
+    // Validate that dataset has items before creating experiment record
+    const targetVersion = config.version ?? dataset.version;
+    const items = await datasetsStore.getItemsByVersion({
+      datasetId: this.id,
+      version: targetVersion,
+    });
+    if (items.length === 0) {
+      throw new MastraError({
+        id: 'EXPERIMENT_NO_ITEMS',
+        text: `Cannot run experiment: dataset "${this.id}" has no items at version ${targetVersion}`,
+        domain: 'STORAGE',
+        category: 'USER',
+      });
+    }
+
     const run = await experimentsStore.createExperiment({
       datasetId: this.id,
-      datasetVersion: dataset.version,
+      datasetVersion: targetVersion,
       targetType: config.targetType ?? 'agent',
       targetId: config.targetId ?? 'inline',
-      totalItems: 0,
+      totalItems: items.length,
       name: config.name,
       description: config.description,
       metadata: config.metadata,
     });
 
     const experimentId = run.id;
 
-    // Fire-and-forget — errors are silently caught
+    // Fire-and-forget — update experiment to failed on unexpected errors
     void runExperiment(this.#mastra, {
       datasetId: this.id,
       experimentId,
       ...config,
-    } as ExperimentConfig).catch(() => {});
+    } as ExperimentConfig).catch(async err => {
+      await experimentsStore
+        .updateExperiment({
+          id: experimentId,
+          status: 'failed',
+          completedAt: new Date(),
+        })
+        .catch(() => {});
+      this.#mastra.getLogger()?.error(`Experiment ${experimentId} failed: ${err?.message ?? err}`);
+    });
 
-    return { experimentId, status: 'pending' as const };
+    return { experimentId, status: 'pending' as const, totalItems: items.length };
   }
 
   /**

packages/core/src/datasets/experiment/__tests__/runExperiment.test.ts

@@ -673,4 +673,54 @@ describe('runExperiment', () => {
       );
     });
   });
+
+  describe('empty dataset handling', () => {
+    it('marks pre-created experiment as failed when dataset has no items', async () => {
+      // Create an empty dataset
+      const emptyDs = await datasetsStorage.createDataset({ name: 'Empty DS' });
+
+      // Pre-create experiment record (simulates async trigger path)
+      const experiment = await experimentsStorage.createExperiment({
+        datasetId: emptyDs.id,
+        datasetVersion: emptyDs.version,
+        targetType: 'agent',
+        targetId: 'test-agent',
+        totalItems: 0,
+      });
+
+      // Run experiment with pre-created ID — should throw and mark as failed
+      await expect(
+        runExperiment(mastra, {
+          datasetId: emptyDs.id,
+          experimentId: experiment.id,
+          targetType: 'agent',
+          targetId: 'test-agent',
+        }),
+      ).rejects.toThrow('No items in dataset');
+
+      // Verify experiment was marked as failed (not stuck in pending)
+      const updated = await experimentsStorage.getExperimentById({ id: experiment.id });
+      expect(updated?.status).toBe('failed');
+      expect(updated?.completedAt).toBeDefined();
+    });
+
+    it('throws without creating experiment record when no pre-created ID', async () => {
+      const emptyDs = await datasetsStorage.createDataset({ name: 'Empty DS 2' });
+
+      await expect(
+        runExperiment(mastra, {
+          datasetId: emptyDs.id,
+          targetType: 'agent',
+          targetId: 'test-agent',
+        }),
+      ).rejects.toThrow('No items in dataset');
+
+      // No experiment record should exist for this dataset
+      const result = await experimentsStorage.listExperiments({
+        datasetId: emptyDs.id,
+        pagination: { page: 0, perPage: 10 },
+      });
+      expect(result.experiments.length).toBe(0);
+    });
+  });
 });