mastra-ai/mastra · error · Error

No env file found for deploy. Add a .env or .env.* file…

Error message

No env file found for deploy. Add a .env or .env.* file before deploying.

What it means

Thrown by readEnvVars when no explicit env file was given and the deploy env-file discovery (getDeployEnvFiles, matching `.env` and `.env.*` in the project directory) found zero candidates. Studio deploys require environment variables, so the CLI refuses to proceed and asks the user to add an env file before deploying.

Solutions

Create a `.env` file at the project root with the required variables, then re-run the deploy.
Or pass an existing file explicitly: `mastra studio deploy --env-file path/to/.env`.
Check the files are at the project root the CLI is run from — `.env` in a parent or child directory won't be found.
In CI, write secrets into a `.env` file in a pre-deploy step.

Example fix

// before
mastra studio deploy   # no .env anywhere
// after
cat > .env <<'EOF'
OPENAI_API_KEY=sk-...
EOF
mastra studio deploy

Defensive patterns

Strategy: validation

Validate before calling

import { readdirSync } from 'node:fs';
const hasEnv = readdirSync(projectDir).some(f => f === '.env' || f.startsWith('.env.'));
if (!hasEnv && !options.envFile) {
  console.error(`No .env/.env.* in ${projectDir}; create one or pass --env-file before deploying.`);
}

Try / catch

try {
  await runStudioDeploy(options);
} catch (err) {
  if ((err as Error).message.includes('No env file found for deploy')) {
    console.error('Create a .env at the project root or pass --env-file <path>.');
    return;
  }
  throw err;
}

Prevention

Maintain a committed `.env.example` and copy it to `.env` during setup.
In CI, write required secrets into a `.env` file before `mastra studio deploy`.
Place env files at the project root the CLI runs from — parent/child directories are not scanned.
Alternatively pass --env-file explicitly to skip discovery.

When it happens

Trigger: Running `mastra studio deploy` in a project directory containing no `.env` or `.env.*` files (and no --env-file option), or where the files are located in a subdirectory other than the project root the CLI scans.

Common situations: Fresh project where env vars live only in the shell or CI secrets but never in a `.env` file; gitignored env files absent on a fresh clone; deploying from a directory copy without env files; `.env` stored one level up from the project root.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

  projectDir: string,
  options: { autoAccept?: boolean; envFile?: string } = {},
): Promise<Record<string, string>> {
  // When an explicit env file is provided, trust the user — read it directly.
  if (options.envFile) {
    const filePath = join(projectDir, options.envFile);
    try {
      await access(filePath);
    } 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,

View on GitHub (pinned to 75dd419e61)