mastra-ai/mastra · error · Error

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

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.

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)

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.