What causes "Directory not found: ${dirArg}.${hint}" in mastra-ai/mastra?

If you meant to deploy to a named environment, use the flag form: `mastra deploy --env staging` instead of `mastra deploy staging`.

mastra-ai/mastra · error · Error

Directory not found: ${dirArg}.${hint}

Error message

Directory not found: ${dirArg}.${hint}

What it means

Thrown by assertDeployDir when the resolved directory argument does not exist or is not a directory. The CLI deploy command's first positional argument is a directory; when it looks like an environment name (no path separators, doesn't start with '.'), the error hints that the user probably meant `mastra deploy --env <name>` instead. This is a fast-fail guard before any build or deploy work happens.

Source

Thrown at packages/cli/src/commands/deploy/validate-dir.ts:21

/**
 * Guard against `mastra deploy staging` silently deploying to production.
 *
 * The deploy signature is `deploy [dir]`, but the rest of the surface teaches
 * positional environments (`env restart staging`, `env db create staging`),
 * so users type `mastra deploy staging` expecting to target that environment.
 * The positional is consumed as a directory, falls back to cwd semantics, and
 * the deploy targets production. Fail fast when the directory doesn't exist
 * and point at `--env` when the argument looks like an environment name.
 */
export async function assertDeployDir(dirArg: string | undefined, resolvedDir: string): Promise<void> {
  if (!dirArg) return;

  const stats = await stat(resolvedDir).catch(() => null);
  if (stats?.isDirectory()) return;

  const looksLikeEnvName = !dirArg.includes('/') && !dirArg.includes('\\') && !dirArg.startsWith('.');
  const hint = looksLikeEnvName ? ` Did you mean: mastra deploy --env ${dirArg}` : '';
  throw new Error(`Directory not found: ${dirArg}.${hint}`);
}

View on GitHub (pinned to 75dd419e61)

Solutions

If you meant to deploy to a named environment, use the flag form: `mastra deploy --env staging` instead of `mastra deploy staging`.
Verify the directory path exists (ls it) and pass a directory, not a file; use an absolute path if unsure.
Run from the project root or pass the correct relative path to your Mastra project directory.
Check for typos in the directory name and for shell quoting issues stripping path separators.

Example fix

// before (misread as a directory)
$ mastra deploy staging
Error: Directory not found: staging. Did you mean: mastra deploy --env staging
// after
$ mastra deploy --env staging

Defensive patterns

Strategy: validation

Validate before calling

import { stat } from 'node:fs/promises';
const target = dirArg ?? process.cwd();
if (!(await stat(target).catch(() => null))?.isDirectory()) {
  throw new Error(`Not a directory: ${target}. For named environments use: mastra deploy --env ${dirArg}`);
}

Prevention

Use `mastra deploy --env <name>` for environments; reserve the positional argument for directories only.
Run deploys from the project root or pass absolute paths.
Verify the target path with ls before invoking the command.
Remember the positional arg must be a directory, not a file.

When it happens

Trigger: stat(resolvedDir) fails or the path is not a directory when calling `mastra deploy <dirArg>`. The hint variant appears when dirArg contains no '/' or '\\' and does not start with '.', e.g. `mastra deploy staging`.

Common situations: Users migrating from `mastra deploy production`/`mastra deploy staging` syntax that assumed an environment name; typo in the directory path; running deploy from the wrong working directory so the relative path doesn't resolve; passing a file path instead of a directory.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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