mastra-ai/mastra · error · Error

Mastra configuration initialization created or modified unex

Error message

Mastra configuration initialization created or modified unexpected files in the experiment worker artifact: ${unexpectedOutputFiles.join(', ')}

What it means

ExperimentBundler.getUserBundlerOptions snapshots the output directory's file signatures before and after invoking the base Bundler's config initialization (which may run user mastra config code), in an isolated scratch cwd. The artifact must contain only deterministic bundler output, so any created, deleted, or modified file other than `bundler-config.mjs` triggers this error. It detects user config code with destructive side effects (e.g. writing to process.cwd() or the output dir) that would corrupt the reproducible worker artifact.

Source

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

    const existingOutputFiles = await collectFileSignatures(outputDirectory);
    const scratchDirectory = await mkdtemp(join(tmpdir(), 'mastra-experiment-config-'));
    const originalWorkingDirectory = process.cwd();
    let bundlerOptions: NonNullable<Config['bundler']>;
    try {
      process.chdir(scratchDirectory);
      bundlerOptions = await super.getUserBundlerOptions(mastraEntryFile, outputDirectory);
    } finally {
      process.chdir(originalWorkingDirectory);
      await rm(scratchDirectory, { recursive: true, force: true });
    }

    const currentOutputFiles = await collectFileSignatures(outputDirectory);
    const outputPaths = new Set([...existingOutputFiles.keys(), ...currentOutputFiles.keys()]);
    const unexpectedOutputFiles = [...outputPaths]
      .filter(path => path !== 'bundler-config.mjs' && existingOutputFiles.get(path) !== currentOutputFiles.get(path))
      .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
    if (unexpectedOutputFiles.length > 0) {
      throw new Error(
        `Mastra configuration initialization created or modified unexpected files in the experiment worker artifact: ${unexpectedOutputFiles.join(', ')}`,
      );
    }

    if (!Array.isArray(bundlerOptions.externals)) return bundlerOptions;

    return {
      ...bundlerOptions,
      dynamicPackages: [...new Set([...(bundlerOptions.dynamicPackages ?? []), ...bundlerOptions.externals])],
    };
  }

  async bundle(
    entryFile: string,
    outputDirectory: string,
    { projectRoot }: { toolsPaths: (string | string[])[]; projectRoot: string },
  ): Promise<void> {
    await this._bundle(this.getEntry(), entryFile, { outputDirectory, projectRoot });

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect the listed file path(s) in the message and find what in your mastra config or its imports writes them.
2. Move file-writing side effects out of module top-level / config initialization into lazy functions called at runtime.
3. Make any unavoidable writes go to a temp directory, not the project/output directory.
4. If the file is legitimately expected, ensure it is identical before and after (same content digest) so the signature comparison passes.

Example fix

// before (mastra config top level)
fs.writeFileSync('./gen/schema.json', buildSchema());
export const mastra = new Mastra({...});
// after
function ensureSchema() { fs.writeFileSync('./gen/schema.json', buildSchema()); }
export const mastra = new Mastra({...});  // call ensureSchema() lazily at runtime, not on import

// audit your mastra config entry for import-time side effects before building
const suspicious = await grepConfigForWrites('./src/mastra'); // no fs.write*/mkdir/unlink at module top level

null

try {
  await buildExperimentWorker({ dir, root, outputDir, debug });
} catch (e) {
  if (String(e?.message).includes('unexpected files in the experiment worker artifact')) {
    console.error('Remove import-time file writes from your mastra config:', e.message);
  } else throw e;
}

When it happens

Trigger: Running an experiment worker build where the user's mastra configuration file (or code it imports) writes, deletes, or modifies files in the bundler output directory during bundler-options initialization — anything other than bundler-config.mjs.

Common situations: mastra.config/index.ts with top-level side effects like fs.writeFileSync, log-file creation, DB migrations, or code generators that emit files at import time; plugins that materialize cache files in cwd; a custom bundler option that touches the output dir.

Related errors

• FAIL_BUILD_SCRIPT
• FAIL_BUILD_COMMAND
• mastra-wrapper plugin did not return code, there is likely a
• Failed to copy studio assets from "${studioSource}" to "${st
• No index.mjs found in "${dir}" — did the build succeed?

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