Failed to parse snapshot ${snapshotPath}: ${err instanceof E

Error message

Failed to parse snapshot ${snapshotPath}: ${err instanceof Error ? err.message : String(err)}

What it means

After reading the snapshot file, TestExporter JSON.parse()s it. If the content is not valid JSON (truncated write, manual edit, merge-conflict markers, encoding issues), the library wraps the parse error with the snapshot path and underlying message so you know which file is corrupt.

Source

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

    }

    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;
    } else if (snapshotData && typeof snapshotData === 'object' && 'spans' in snapshotData) {
      // New format: { __structure__, spans }
      expectedSpans = snapshotData.spans;
      expectedStructure = snapshotData.__structure__;
    } else {
      throw new Error(
        `Invalid snapshot format in ${snapshotPath}.\n` + `Expected an array or object with 'spans' property.`,
      );
    }

View on GitHub (pinned to 75dd419e61)

Solutions

Open the reported snapshot file and inspect the underlying JSON syntax error in the wrapped message
Delete the corrupt file and regenerate with { updateSnapshot: true }
If caused by a merge conflict, resolve by regenerating the snapshot rather than hand-merging
Ensure no build step writes non-JSON content to snapshot-named files

Example fix

// before (snapshot.json contains '<<<<<<< HEAD')
$ rm .snapshots/test.json
// after
const exporter = new TestExporter({ updateSnapshot: true }); // regenerates valid JSON

Defensive patterns

Strategy: validation

Validate before calling

const content = await readFile(path, 'utf-8');
try { JSON.parse(content); } catch (e) {
  throw new Error(`Corrupt snapshot ${path}; regenerate with updateSnapshot: true`);
}

Type guard

function isParseableJson(text: string): boolean {
  try { JSON.parse(text); return true; } catch { return false; }
}

Try / catch

try {
  await exporter.export(spans, callback);
} catch (err) {
  if ((err as Error).message.startsWith('Failed to parse snapshot')) {
    await rm(snapshotPath);
    await new TestExporter({ updateSnapshot: true }).export(spans, callback);
  } else throw err;
}

Prevention

Never hand-edit snapshot files; regenerate instead
Resolve merge conflicts by regenerating snapshots, not textual merges
Check for git conflict markers (<<<<<<<) before running comparisons
Avoid interrupting updateSnapshot runs mid-write

When it happens

Trigger: The file at snapshotPath exists but contains invalid JSON — partially written output from a crashed update run, hand-edited snapshots, git conflict markers (<<<<<<<) in the file, or non-JSON content saved under the snapshot name.

Common situations: Merge conflicts in committed snapshots resolved textually but never re-validated; interrupted test runs leaving truncated files; editor saves with non-UTF8 or trailing garbage.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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