mastra-ai/mastra · error · Error

Refusing to overwrite ${target}. Re-run with --force to repl

Error message

Refusing to overwrite ${target}. Re-run with --force to replace it.

What it means

`mastra env vars pull` writes the output file with flag 'wx' (fail if exists) unless --force is given, so an existing `.env` (or -o target) is never silently clobbered. When the write fails with EEXIST, the CLI converts it into this explicit refusal. It is a safety guard against destroying local env files that may contain uncommitted local values.

Source

Thrown at packages/cli/src/commands/env/vars.ts:93

  // vars first, project-scoped vars override on conflict.
  const merged = { ...(environment.envVars ?? {}), ...projectVars };

  const { content, written, skipped } = serializeEnvFile(merged, {
    header: `Pulled from Mastra environment ${environment.slug} — do not edit manually`,
    managedVarNames: environment.managedEnvVarNames,
  });

  const target = options.output ?? '.env';
  const outputPath = resolve(target);
  try {
    await writeFile(outputPath, content, {
      encoding: 'utf-8',
      mode: 0o600,
      flag: options.force ? 'w' : 'wx',
    });
  } catch (error) {
    if (isAlreadyExistsError(error)) {
      throw new Error(`Refusing to overwrite ${target}. Re-run with --force to replace it.`);
    }
    throw error;
  }
  await chmod(outputPath, 0o600);

  if (written === 0) {
    console.info(`\n  No env vars set on ${environment.slug}. Wrote empty ${target}.\n`);
  } else {
    console.info(
      `\n  Pulled ${written} variable(s) from ${environment.slug} to ${target}.${skipped > 0 ? ` Skipped ${skipped} unsafe key(s).` : ''}\n`,
    );
  }
  const managedCount = environment.managedEnvVarNames?.length ?? 0;
  if (managedCount > 0) {
    console.info(
      `  ${managedCount} managed variable name(s) listed as comments — values are injected at deploy time.\n`,
    );
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Re-run with `--force` to deliberately replace the file: `mastra env vars pull production --force`.
2. Use `-o/--output` to write to a different file, e.g. `mastra env vars pull -o .env.pulled`, then diff manually.
3. Back up the existing file before forcing: `cp .env .env.bak` then re-run with --force.
4. In automation, check existence first and decide programmatically whether to pass --force.

Example fix

// before
mastra env vars pull production
// error: Refusing to overwrite .env ...
// after
mastra env vars pull production --force

import { existsSync } from 'node:fs';
if (existsSync(outputPath) && !options.force) {
  throw new Error(`${outputPath} exists; pass --force or choose another -o path`);
}

null

try {
  await envVarsPullAction(envArg, options);
} catch (e) {
  if (e instanceof Error && e.message.includes('Refusing to overwrite')) {
    // prompt user or retry with force
  } else throw e;
}

When it happens

Trigger: Running `mastra env vars pull` when the output file (default `.env`, or the --output path) already exists on disk and the `--force` flag was not passed.

Common situations: Pulling into a project that already has a hand-maintained `.env`; re-running a pull script twice; CI or scripts re-invoking the command on a checked-out repo that ships a `.env.example`-style committed `.env`.

Related errors

• Directory ${path.basename(targetPath)} already exists
• Project name must be 1-214 lowercase characters, start with
• A file or directory named "${projectName}" already exists. P
• .mastra/output/index.mjs not found — did the build succeed?
• Directory not found: ${dirArg}.${hint}

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