{"record":{"id":"f47d2fbc66b2f94f","repo":"mastra-ai/mastra","slug":"invalid-snapshot-format-in-snapshotpath-expect","errorCode":null,"errorMessage":"Invalid snapshot format in ${snapshotPath}.\nExpected an array or object with 'spans' property.","messagePattern":"Invalid snapshot format in (.+?)\\.\nExpected an array or object with 'spans' property\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"observability/mastra/src/exporters/test.ts","lineNumber":1318,"sourceCode":"    try {\n      snapshotData = JSON.parse(snapshotContent);\n    } catch (err: unknown) {\n      throw new Error(`Failed to parse snapshot ${snapshotPath}: ${err instanceof Error ? err.message : String(err)}`);\n    }\n\n    // Handle both old format (array) and new format (object with __structure__ and spans)\n    let expectedSpans: unknown;\n    let expectedStructure: string[] | undefined;\n\n    if (Array.isArray(snapshotData)) {\n      // Old format: just the spans array\n      expectedSpans = snapshotData;\n    } else if (snapshotData && typeof snapshotData === 'object' && 'spans' in snapshotData) {\n      // New format: { __structure__, spans }\n      expectedSpans = snapshotData.spans;\n      expectedStructure = snapshotData.__structure__;\n    } else {\n      throw new Error(\n        `Invalid snapshot format in ${snapshotPath}.\\n` + `Expected an array or object with 'spans' property.`,\n      );\n    }\n\n    // Compare structure first (quick validation)\n    if (expectedStructure) {\n      const structureMismatches = this.#compareStructure(structureGraph, expectedStructure);\n      if (structureMismatches.length > 0) {\n        throw new Error(\n          `Structure mismatch in snapshot:\\n\\n` +\n            `Expected:\\n${expectedStructure.join('\\n')}\\n\\n` +\n            `Actual:\\n${structureGraph.join('\\n')}\\n\\n` +\n            `Differences:\\n${structureMismatches.join('\\n')}\\n\\n` +\n            `Snapshot: ${snapshotPath}\\n` +\n            `Run with { updateSnapshot: true } to update.`,\n        );\n      }\n    }","sourceCodeStart":1300,"sourceCodeEnd":1336,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/observability/mastra/src/exporters/test.ts#L1300-L1336","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before (snapshot.json)\n{}\n// after\nconst exporter = new TestExporter({ updateSnapshot: true });\n// writes { \"__structure__\": [...], \"spans\": [...] }","handlingStrategy":"validation","validationCode":"const data = JSON.parse(await readFile(path, 'utf-8'));\nconst valid = Array.isArray(data) || (data && typeof data === 'object' && 'spans' in data);\nif (!valid) throw new Error(`Unsupported snapshot schema in ${path}; regenerate.`);","typeGuard":"function isSnapshotData(v: unknown): v is unknown[] | { spans: unknown[]; __structure__?: string[] } {\n  return Array.isArray(v) || (typeof v === 'object' && v !== null && 'spans' in v);\n}","tryCatchPattern":"try {\n  await exporter.export(spans, callback);\n} catch (err) {\n  if ((err as Error).message.startsWith('Invalid snapshot format')) {\n    await new TestExporter({ updateSnapshot: true }).export(spans, callback);\n  } else throw err;\n}","preventionTips":["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"],"tags":["snapshots","schema-validation","format","filesystem"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}