mastra-ai/mastra · error

Snapshot has ${mismatches.length} mismatch${mismatches.lengt

Error message

Snapshot has ${mismatches.length} mismatch${mismatches.length > 1 ? 'es' : ''}:

${mismatchDetails}

Snapshot: ${snapshotPath}
Run with { updateSnapshot: true } to update.

What it means

After the structure check passes, assertMatchesSnapshot deep-compares the normalized span tree against the snapshot's 'spans' section using marker-aware comparison (__or__, __any__ wildcards). Each field that differs (path, expected, actual) is collected, and if any exist it throws an aggregate error listing every mismatch. Unlike error 825 this compares span content (attributes, status, names), not just shape.

Source

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

            `Differences:\n${structureMismatches.join('\n')}\n\n` +
            `Snapshot: ${snapshotPath}\n` +
            `Run with { updateSnapshot: true } to update.`,
        );
      }
    }

    // Deep compare spans
    const mismatches: { path: string; expected: unknown; actual: unknown }[] = [];
    this.#deepCompareWithMarkers(normalizedTree, expectedSpans, '$.spans', mismatches);

    if (mismatches.length > 0) {
      const mismatchDetails = mismatches
        .map(
          (m, i) =>
            `${i + 1}. ${m.path}\n   Expected: ${JSON.stringify(m.expected)}\n   Actual:   ${JSON.stringify(m.actual)}`,
        )
        .join('\n\n');
      throw new Error(
        `Snapshot has ${mismatches.length} mismatch${mismatches.length > 1 ? 'es' : ''}:\n\n` +
          `${mismatchDetails}\n\n` +
          `Snapshot: ${snapshotPath}\n` +
          `Run with { updateSnapshot: true } to update.`,
      );
    }
  }

  /**
   * Compare two structure graphs and return differences
   */
  #compareStructure(actual: string[], expected: string[]): string[] {
    const diffs: string[] = [];

    const maxLen = Math.max(actual.length, expected.length);
    for (let i = 0; i < maxLen; i++) {
      const actualLine = actual[i];
      const expectedLine = expected[i];

View on GitHub (pinned to 75dd419e61)

Solutions

1. Review the numbered mismatch list; fix the actual span values if the snapshot is the source of truth.
2. Replace brittle exact values in the snapshot with markers like {"__any__":"number"} or {"__or__":[...]} for volatile fields.
3. Re-record with { updateSnapshot: true } if the new values are the intended baseline.
4. Pin model/provider/test inputs so attributes are deterministic, then update the snapshot once.

Example fix

// snapshot before (brittle)
"usage": { "totalTokens": 42 }
// snapshot after (marker for volatile field)
"usage": { "totalTokens": { "__any__": "number" } }

const snap = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
// detect volatile fields recorded as exact numbers that should use markers
if (JSON.stringify(snap).includes('"totalTokens":')) console.warn('Snapshot may contain volatile token counts; consider __any__ markers');

function isSnapshotValue(v: unknown): boolean {
  if (v === null || typeof v !== 'object') return true;
  return '__any__' in (v as object) || '__or__' in (v as object);
}

try {
  await exporter.assertMatchesSnapshot('agent-trace.snap');
} catch (err) {
  const msg = err instanceof Error ? err.message : String(err);
  if (msg.startsWith('Snapshot has')) {
    console.error(msg); // mismatch list includes per-path expected/actual
    if (process.env.UPDATE_SNAPSHOTS) return exporter.assertMatchesSnapshot('agent-trace.snap', { updateSnapshot: true });
  }
  throw err;
}

When it happens

Trigger: Calling assertMatchesSnapshot when span field values differ from the snapshot: changed model IDs, token counts, durations, span names, statuses, or attribute values that are not covered by __any__/__or__ markers in the snapshot.

Common situations: Snapshot recorded with different model or provider settings; volatile fields (usage counts, timestamps) that lack __any__ markers; locale/format changes in attribute values; stale snapshots after code changes to span attribute computation.

Related errors

• Structure mismatch in snapshot: Expected: ${expectedStructu
• DURABLE_AGENT_RECOVER_SNAPSHOT_NOT_FOUND
• DURABLE_AGENT_RECOVER_INVALID_SNAPSHOT
• DURABLE_AGENT_RESUME_INVALID_SNAPSHOT
• OBSERVABILITY_STORAGE_BATCH_UPDATE_SPANS_NOT_IMPLEMENTED

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