mastra-ai/mastra · error · Error

Env file not found: ${options.envFile}

Error message

Env file not found: ${options.envFile}

What it means

Thrown by readEnvVars in the studio deploy command when an explicit env file is passed via options (e.g., `--env-file <path>`) but the file cannot be accessed (fs.access fails) relative to the project directory. The CLI trusts the user's explicit path and errors immediately rather than falling back to discovery.

Source

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

        (entry.name === '.env' || entry.name.startsWith('.env.')) &&
        !entry.name.endsWith('.example') &&
        entry.name !== '.env.schema',
    )
    .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

1. Verify the file exists relative to the project directory (not your shell's cwd): `ls <projectDir>/<envFile>`.
2. Pass a path relative to the project root or use an absolute path for --env-file.
3. Create the env file or copy it from a template before deploying.
4. If CI, ensure the env file is generated/uploaded as a build artifact before the deploy step.

Example fix

// before
mastra studio deploy --env-file .env.prod   // typo
// after
mastra studio deploy --env-file .env.production

import { access } from 'node:fs/promises';
import { join, isAbsolute } from 'node:path';
const p = isAbsolute(envFile) ? envFile : join(projectDir, envFile);
try {
  await access(p);
} catch {
  throw new Error(`--env-file not found at ${p} (resolved against project dir ${projectDir})`);
}

try {
  await runStudioDeploy(options);
} catch (err) {
  if ((err as Error).message.startsWith('Env file not found:')) {
    console.error(`${err.message} — note the path is resolved relative to the project directory.`);
    return;
  }
  throw err;
}

When it happens

Trigger: Running `mastra studio deploy --env-file <path>` where the path is misspelled, relative to the wrong directory (it's resolved against projectDir, not cwd), points outside the project, or the file was deleted/not committed.

Common situations: Using `.env.production` without creating it; passing a path relative to cwd while the CLI resolves it relative to the project root; gitignored env file missing on a CI machine; typo in the filename.

Related errors

• Env file not found: ${options.envFile}
• .mastra/output/index.mjs not found — did the build succeed?
• Directory not found: ${dirArg}.${hint}
• No env file found for deploy. Add a .env or .env.* file befo
• Multiple env files found: ${availableDeployEnvFiles.join(',

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