What causes "Env file not found: ${options.envFile}" in mastra-ai/mastra?

Create the env file at the specified path relative to projectDir

Env file not found: ${options.envFile}

Error message

Env file not found: ${options.envFile}

What it means

`readEnvVars` validates that an explicitly provided env file exists before parsing it. When --env-file (options.envFile) is given, the CLI checks file accessibility with fs.access and throws this error naming the file if it cannot be reached. Explicitly provided files are trusted as-is, so a missing file is a hard error rather than a silent fallback.

Source

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

        (entry.isFile() || entry.isSymbolicLink()) &&
        (entry.name === '.env' || entry.name.startsWith('.env.')) &&
        !entry.name.endsWith('.example'),
    )
    .map(entry => entry.name)
    .sort((a, b) => a.localeCompare(b));
}

export async function readEnvVars(
  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.`,

View on GitHub (pinned to 75dd419e61)

Solutions

Create the env file at the specified path relative to projectDir
Correct the --env-file path or typo
Run the command from the project root so the relative path resolves correctly

Example fix

// before
mastra server deploy --env-file .env.porduction
// after
mastra server deploy --env-file .env.production

Defensive patterns

Strategy: validation

Validate before calling

import { accessSync, constants } from 'node:fs';
const filePath = join(projectDir, options.envFile);
try {
  accessSync(filePath, constants.F_OK);
} catch {
  throw new Error(`--env-file '${options.envFile}' not found relative to ${projectDir}`);
}

Type guard

const envFileExists = (dir: string, name: string): boolean => {
  try { accessSync(join(dir, name), constants.F_OK); return true; } catch { return false; }
};

Try / catch

try {
  await runServerDeploy(opts);
} catch (e) {
  if ((e as Error).message.startsWith('Env file not found')) {
    console.error('Fix --env-file path relative to the project directory.');
  } else throw e;
}

Prevention

Always pass --env-file relative to the project root
Double-check spelling of env file names
Create the env file before running deploy in CI
Run deploys from the project directory

When it happens

Trigger: Running `mastra server deploy --env-file <path>` where <path> (resolved against projectDir) does not exist or is not accessible.

Common situations: Typo in the --env-file value; running the deploy from a different working directory than expected; env file deleted or gitignored and absent on CI.

Related errors

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