mastra-ai/mastra · critical · Error

#mastra does not provide an export named 'mastra'

Error message

#mastra does not provide an export named 'mastra'

What it means

The experiment worker entry point imports the user's Mastra instance via the `#mastra` package specifier and destructures the `mastra` export. If the resolved module exports nothing named `mastra` (falsy), the worker aborts at startup with this error. The experiment runner requires a single canonical `mastra` export to enumerate agents/workflows for the run.

Source

Thrown at packages/cli/src/commands/experiment/ExperimentBundler.ts:151

    };
    await writeFile(join(outputDirectory, 'experiment-worker-manifest.json'), JSON.stringify(manifest, null, 2));
  }

  protected getEntry(): string {
    const runtimePath = resolveRuntimePath();
    return `
import { readFile } from 'node:fs/promises';
import { runExperimentWorker } from ${JSON.stringify(runtimePath)};

console.log = (...args) => console.error(...args);
console.info = (...args) => console.error(...args);
console.debug = (...args) => console.error(...args);
const [{ runExperiment }, mastraModule] = await Promise.all([
  import('@mastra/core/datasets'),
  import('#mastra'),
]);
const { mastra } = mastraModule;
if (!mastra) throw new Error("#mastra does not provide an export named 'mastra'");
const artifactManifest = JSON.parse(
  await readFile(new URL('./experiment-worker-manifest.json', import.meta.url), 'utf8'),
);
const exitCode = await runExperimentWorker({
  mastra,
  runExperiment,
  build: {
    buildId: artifactManifest.build.buildId,
    protocolVersion: artifactManifest.protocol.versions[0],
    datasetCanonicalizationVersion: artifactManifest.protocol.datasetCanonicalizationVersion,
  },
});
await Promise.race([
  new Promise(resolve => process.stdout.end(resolve)),
  new Promise(resolve => setTimeout(resolve, 5_000)),
]);
process.exit(exitCode);
`;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure src/mastra/index.ts contains `export const mastra = new Mastra({...})` (named export, exactly `mastra`).
2. Check for typos or renames like `export const m = ...` and fix the export name.
3. Remove conditional branches that can leave `mastra` undefined; the export must always be defined.
4. Rebuild the experiment worker after fixing, then re-run.

Example fix

// before (src/mastra/index.ts)
export const mastraInstance = new Mastra({ agents: {} });
// after
export const mastra = new Mastra({ agents: {} });

// in src/mastra/index.ts, verify before shipping:
const mod = await import('./src/mastra/index.js');
if (!('mastra' in mod) || !mod.mastra) throw new Error('src/mastra/index.ts must export a defined `mastra`');

function hasMastraExport(mod: unknown): mod is { mastra: NonNullable<unknown> } {
  return typeof mod === 'object' && mod !== null && 'mastra' in mod && (mod as any).mastra != null;
}

try {
  await runExperimentWorker({ mastra, runExperiment, build });
} catch (e) {
  if (e instanceof Error && e.message.includes("export named 'mastra'")) {
    console.error('Add `export const mastra = new Mastra({...})` to your mastra index');
  } else throw e;
}

When it happens

Trigger: The bundled user source (the `#mastra` import target, e.g. src/mastra/index.ts) does not export a `mastra` binding, exports it under a different name, or conditionally exports undefined (e.g. from a branch that failed to initialize).

Common situations: Index file exports `export const mastra = new Mastra()` missing after a refactor; only default export present; export renamed to `mastraInstance`; tree-shaking or an accidental re-export shadowing `mastra`; partial file where `new Mastra(...)` is commented out.

Related errors

• Response body is null
• Response body is null
• execa is not available in Cloudflare Workers
• require(${specifier}) is not available in Cloudflare Workers
• Plugin module must export a plugin object as default or name

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