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

Error message

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

What it means

When no --env-file is given, `readEnvVars` scans the project directory for deployable env files (.env, .env.*). If none exist, it throws this error because a server deploy requires environment variables to be packaged.

Source

Thrown at packages/cli/src/commands/server/deploy.ts:131

  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)

Solutions

Create a .env file in the project root with the required variables
Or pass an explicit file: `mastra server deploy --env-file <path>`
Restore/copy the env file in CI from your secrets manager

Example fix

// before
# no .env in project
// after
printf 'MASTRA_API_KEY=xxx\n' > .env && mastra server deploy

Defensive patterns

Strategy: validation

Validate before calling

import { readdirSync } from 'node:fs';
const envFiles = readdirSync(projectDir).filter(f => f === '.env' || f.startsWith('.env.'));
if (envFiles.length === 0) {
  throw new Error('Create a .env file before deploying.');
}

Type guard

const hasEnvFile = (dir: string): boolean =>
  readdirSync(dir).some(f => f === '.env' || f.startsWith('.env.'));

Try / catch

try {
  await runServerDeploy(opts);
} catch (e) {
  if ((e as Error).message.startsWith('No env file found')) {
    console.error('Add a .env or .env.* file to the project root.');
  } else throw e;
}

Prevention

Commit a .env.example and generate .env in setup steps
Inject env files from your secrets manager in CI
Document required env vars for deploys
Run a pre-deploy check for env file presence

When it happens

Trigger: Running `mastra server deploy` without --env-file in a project directory containing no .env or .env.* files.

Common situations: Fresh checkout where .env is gitignored and never created; CI environment without secrets materialized; renamed env files (e.g. .environment) the scanner doesn't recognize.

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/b9b204827685db5a. Report an issue: GitHub.