Snapshot file not found: ${snapshotPath} Run with { updateSn

Error message

Snapshot file not found: ${snapshotPath}
Run with { updateSnapshot: true } to create it.

What it means

When updateSnapshot is falsy, TestExporter reads the existing snapshot file for comparison. If the file does not exist (fs ENOENT), it rethrows as this descriptive error rather than a raw ENOENT, instructing the developer to run with { updateSnapshot: true } to create the baseline.

Source

Thrown at observability/mastra/src/exporters/test.ts:1294

    // Check option to update snapshot
    const shouldUpdate = options?.updateSnapshot;

    // If updating snapshot, write and return
    if (shouldUpdate) {
      const { writeFile } = await import('node:fs/promises');
      await writeFile(snapshotPath, currentJson, 'utf-8');
      this.logger.info(`TestExporter: updated snapshot ${snapshotPath}`);
      return;
    }

    let snapshotData: { __structure__?: string[]; spans?: unknown } | unknown[];
    let snapshotContent: string;
    try {
      const { readFile } = await import('node:fs/promises');
      snapshotContent = await readFile(snapshotPath, 'utf-8');
    } catch (err: unknown) {
      if (err && typeof err === 'object' && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
        throw new Error(
          `Snapshot file not found: ${snapshotPath}\n` + `Run with { updateSnapshot: true } to create it.`,
        );
      }
      throw err;
    }
    try {
      snapshotData = JSON.parse(snapshotContent);
    } catch (err: unknown) {
      throw new Error(`Failed to parse snapshot ${snapshotPath}: ${err instanceof Error ? err.message : String(err)}`);
    }

    // Handle both old format (array) and new format (object with __structure__ and spans)
    let expectedSpans: unknown;
    let expectedStructure: string[] | undefined;

    if (Array.isArray(snapshotData)) {
      // Old format: just the spans array
      expectedSpans = snapshotData;

View on GitHub (pinned to 75dd419e61)

Solutions

Run once with { updateSnapshot: true } to create the snapshot file
Restore the missing snapshot file from version control (commit snapshots if they are intended baselines)
Verify snapshotPath/snapshotsDir points at the directory where snapshots actually live
Fix CI so snapshot fixtures are checked out, not gitignored

Example fix

// before
const exporter = new TestExporter(); // compares against missing snapshot
// after
const exporter = new TestExporter({ updateSnapshot: true }); // first run creates baseline

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
const snapshotPath = resolveSnapshotPath(suite);
if (!existsSync(snapshotPath)) {
  throw new Error(`Snapshot missing: ${snapshotPath}. Run once with updateSnapshot: true.`);
}

Type guard

function snapshotExists(p: string | undefined | null): p is string {
  return typeof p === 'string' && p.length > 0 && existsSync(p);
}

Try / catch

try {
  await exporter.export(spans, callback);
} catch (err) {
  if ((err as Error).message.startsWith('Snapshot file not found')) {
    await new TestExporter({ updateSnapshot: true }).export(spans, callback);
  } else throw err;
}

Prevention

Run the updateSnapshot pass after adding/renaming suites
Commit snapshot baselines or generate them in a pre-CI step
Don't gitignore snapshot directories used for comparison
Verify snapshotsDir resolves to the intended path

When it happens

Trigger: Running the TestExporter snapshot comparison where snapshotPath points to a file that was never generated, was deleted, was moved, or was excluded by .gitignore / clean scripts.

Common situations: Fresh clone where snapshots are gitignored; CI checkout missing snapshot fixtures; renaming a test suite without regenerating its snapshot; machine that never executed the update pass.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/d8b1f4562f5ac2f4. Report an issue: GitHub.