mastra-ai/mastra · error · Error

Multiple env files found: ${availableDeployEnvFiles.join(',

Error message

Multiple env files found: ${availableDeployEnvFiles.join(', ')}. Use --env-file to specify which one to deploy.

What it means

The `mastra studio deploy` command automatically detects env files (.env, .env.production, etc.) in the target directory. When more than one candidate env file exists, the command refuses to guess which one to upload in non-interactive mode and throws, telling you to disambiguate with --env-file. Interactive runs instead prompt with a default of .env.production.

Source

Thrown at packages/cli/src/commands/studio/deploy.ts:162

    } catch {
      throw new Error(`Env file not found: ${options.envFile}`);
    }
    p.log.step(`Using env file: ${options.envFile}`);
    return parseEnvFile(await readFile(filePath, 'utf-8'));
  }

  const availableDeployEnvFiles = await getDeployEnvFiles(projectDir);

  if (availableDeployEnvFiles.length === 0) {
    throw new Error('No env file found for deploy. Add a .env or .env.* file before deploying.');
  }

  let selectedEnvFile: string;

  if (availableDeployEnvFiles.length === 1) {
    selectedEnvFile = availableDeployEnvFiles[0]!;
  } else if (options.autoAccept) {
    throw new Error(
      `Multiple env files found: ${availableDeployEnvFiles.join(', ')}. Use --env-file to specify which one to deploy.`,
    );
  } else {
    const defaultFile =
      availableDeployEnvFiles.find(envFile => envFile === '.env.production') ?? availableDeployEnvFiles[0]!;

    const selected = await p.select({
      message: 'Choose env file to deploy',
      options: availableDeployEnvFiles.map(envFile => ({ value: envFile, label: envFile })),
      initialValue: defaultFile,
    });

    if (p.isCancel(selected)) {
      p.cancel('Deploy cancelled.');
      process.exit(0);
    }

    selectedEnvFile = selected as string;

View on GitHub (pinned to 75dd419e61)

Solutions

Pass --env-file explicitly, e.g. `mastra studio deploy --env-file .env.production`
Remove or rename the env files you do not want deployed so only one candidate remains
Run without --yes and pick the file interactively
In CI, ensure only the intended env file exists in the build directory before deploying

Example fix

// before
mastra studio deploy --yes
// Error: Multiple env files found: .env, .env.production
// after
mastra studio deploy --yes --env-file .env.production

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
const candidates = ['.env', '.env.production', '.env.local'].map(f => join(dir, f)).filter(f => existsSync(f));
if (candidates.length > 1) {
  throw new Error(`Ambiguous env files: ${candidates.join(', ')}. Pass --env-file.`);
}

Type guard

function hasSingleEnvFile(files: string[]): files is [string] {
  return files.length === 1;
}

Try / catch

try {
  await deploy({ envFile: process.env.DEPLOY_ENV_FILE });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Multiple env files found')) {
    console.error('Disambiguate with --env-file; candidates:', listEnvFiles(dir));
    process.exitCode = 2;
  } else throw e;
}

Prevention

Keep exactly one deploy env file in the build directory; generate .env.production only in prod pipelines
Standardize on --env-file in CI scripts instead of relying on auto-detection
Add a pre-deploy lint step that fails on multiple env files
Document which env file is canonical for deploys in the repo README

When it happens

Trigger: Running `mastra studio deploy --yes` (or with MASTRA_API_TOKEN set, which forces autoAccept) in a directory where readEnvVars finds two or more deploy env files (e.g. both .env and .env.production).

Common situations: Repos that keep a local .env plus a .env.production for staging; CI runners where a prior step generated .env.production alongside a committed .env; switching from dev to prod deploys without cleaning up old env files.

Related errors

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