Snapshot functionality requires a Node.js environment. impor

Error message

Snapshot functionality requires a Node.js environment. import.meta.url is not available in this runtime.

What it means

The TestExporter's snapshot feature resolves its snapshot directory from this module's own file path via import.meta.url. This is only valid in Node.js (or runtimes implementing import.meta.url and node: builtins). The library throws this lazily — at snapshot time, not import time — when the runtime doesn't provide import.meta.url, so bundles targeting browsers/edge runtimes fail with a clear message instead of an opaque TypeError.

Source

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

 * - In-memory event collection for ALL signals (Traces, Metrics, Logs, Scores, Feedback)
 * - File output support
 * - Span lifecycle tracking and validation
 * - Query methods for filtering spans by type, trace ID, span ID, etc.
 * - Query methods for filtering logs, metrics, scores, and feedback
 * - Statistics and analytics on all collected signals
 * - Internal metrics collection with summary on flush()
 */

/**
 * Lazily compute the snapshots directory.
 * Node.js-only: uses dynamic imports so the module can be loaded in edge runtimes
 * without failing at import time.
 */
let _snapshotsDir: string | undefined;
async function getSnapshotsDir(): Promise<string> {
  if (!_snapshotsDir) {
    if (typeof import.meta.url !== 'string') {
      throw new Error(
        'Snapshot functionality requires a Node.js environment. ' + 'import.meta.url is not available in this runtime.',
      );
    }
    const { fileURLToPath } = await import('node:url');
    const { dirname, join } = await import('node:path');
    const __filename = fileURLToPath(import.meta.url);
    const __dirname = dirname(__filename);
    _snapshotsDir = join(__dirname, '..', '__snapshots__');
  }
  return _snapshotsDir;
}

import type {
  TracingEvent,
  TracingEventType,
  AnyExportedSpan,
  ExportedSpan,
  SpanType,

View on GitHub (pinned to 75dd419e61)

Solutions

Run the code in Node.js — the snapshot feature is Node-only by design
Change the bundler platform/target to 'node' so import.meta.url and node: builtins are preserved
Keep snapshot-dependent modules out of client/edge bundles; gate snapshot usage behind a Node-only code path
Use a non-snapshot exporter (e.g. console/in-memory exporter) in non-Node runtimes

Example fix

// before (edge/browser bundle)
exporter.export(spans, () => {}); // snapshot path -> throws
// after
if (typeof process !== 'undefined' && process.versions?.node) {
  exporter.export(spans, () => {});
} else {
  inMemoryExporter.export(spans, () => {});
}

Defensive patterns

Strategy: fallback

Validate before calling

if (typeof import.meta.url !== 'string' || typeof process === 'undefined' || !process.versions?.node) {
  throw new Error('Snapshot APIs require Node.js; use a non-snapshot exporter in this runtime.');
}

Type guard

function isNodeRuntime(): boolean {
  return (
    typeof import.meta.url === 'string' &&
    typeof process !== 'undefined' &&
    !!process.versions?.node
  );
}

Try / catch

try {
  exporter.export(spans, callback);
} catch (err) {
  if ((err as Error).message.includes('import.meta.url is not available')) {
    fallbackExporter.export(spans, callback); // non-snapshot path
  } else {
    throw err;
  }
}

Prevention

Keep snapshot-dependent modules out of browser/edge bundles (platform: 'node' in bundler config)
Gate snapshot usage behind a runtime check before constructing TestExporter
Use a plain in-memory exporter for non-Node targets

When it happens

Trigger: Calling snapshotPath (or any snapshot API on TestExporter, e.g. export with updateSnapshot) from code bundled/executed in a non-Node runtime such as a browser, edge worker, or sandbox where import.meta.url is undefined or not a string.

Common situations: Bundling test-exporter code with a browser/edge platform target; executing in Cloudflare Workers or other edge sandboxes; importing the module into SSR/browser observability tooling.

Related errors

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