Invalid snapshot format in ${snapshotPath}. Expected an arra

Error message

Invalid snapshot format in ${snapshotPath}.
Expected an array or object with 'spans' property.

What it means

The snapshot file parsed as valid JSON but matches neither supported schema: the old format (a plain array of spans) or the new format (an object with a 'spans' property). The library throws this to catch structurally wrong snapshots instead of comparing against undefined and producing confusing failures.

Source

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

    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.`,
      );
    }

    // Compare structure first (quick validation)
    if (expectedStructure) {
      const structureMismatches = this.#compareStructure(structureGraph, expectedStructure);
      if (structureMismatches.length > 0) {
        throw new Error(
          `Structure mismatch in snapshot:\n\n` +
            `Expected:\n${expectedStructure.join('\n')}\n\n` +
            `Actual:\n${structureGraph.join('\n')}\n\n` +
            `Differences:\n${structureMismatches.join('\n')}\n\n` +
            `Snapshot: ${snapshotPath}\n` +
            `Run with { updateSnapshot: true } to update.`,
        );
      }
    }

View on GitHub (pinned to 75dd419e61)

Solutions

Delete the malformed snapshot and regenerate with { updateSnapshot: true } so the library writes a valid schema
Fix the file to be either [ ...spans ] or { __structure__: [...], spans: [...] }
Update any custom tooling that writes these files to the supported schema
Confirm the file belongs to this library and not a different exporter's format

Example fix

// before (snapshot.json)
{}
// after
const exporter = new TestExporter({ updateSnapshot: true });
// writes { "__structure__": [...], "spans": [...] }

Defensive patterns

Strategy: validation

Validate before calling

const data = JSON.parse(await readFile(path, 'utf-8'));
const valid = Array.isArray(data) || (data && typeof data === 'object' && 'spans' in data);
if (!valid) throw new Error(`Unsupported snapshot schema in ${path}; regenerate.`);

Type guard

function isSnapshotData(v: unknown): v is unknown[] | { spans: unknown[]; __structure__?: string[] } {
  return Array.isArray(v) || (typeof v === 'object' && v !== null && 'spans' in v);
}

Try / catch

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

Prevention

Let the library write snapshots; never create placeholder files like {}
Validate snapshot shape in custom tooling before committing
Validate snapshots match the schema (array or { __structure__, spans })
Align snapshot-producing tool versions with the library version

When it happens

Trigger: A snapshot whose parsed JSON is e.g. {} or another object without a 'spans' property, a primitive root, or a file written by incompatible/in-house tooling with a different schema.

Common situations: Hand-editing a snapshot into an unintended shape; format-version changes partially migrated by scripts; creating an empty '{}' placeholder to appease a missing-file check; mixing snapshots from an incompatible fork or older tool version.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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