{"record":{"id":"2d369bd5cb561e8b","repo":"mastra-ai/mastra","slug":"directory-not-found-dirarg-hint","errorCode":null,"errorMessage":"Directory not found: ${dirArg}.${hint}","messagePattern":"Directory not found: (.+?)\\.(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/deploy/validate-dir.ts","lineNumber":21,"sourceCode":"/**\n * Guard against `mastra deploy staging` silently deploying to production.\n *\n * The deploy signature is `deploy [dir]`, but the rest of the surface teaches\n * positional environments (`env restart staging`, `env db create staging`),\n * so users type `mastra deploy staging` expecting to target that environment.\n * The positional is consumed as a directory, falls back to cwd semantics, and\n * the deploy targets production. Fail fast when the directory doesn't exist\n * and point at `--env` when the argument looks like an environment name.\n */\nexport async function assertDeployDir(dirArg: string | undefined, resolvedDir: string): Promise<void> {\n  if (!dirArg) return;\n\n  const stats = await stat(resolvedDir).catch(() => null);\n  if (stats?.isDirectory()) return;\n\n  const looksLikeEnvName = !dirArg.includes('/') && !dirArg.includes('\\\\') && !dirArg.startsWith('.');\n  const hint = looksLikeEnvName ? ` Did you mean: mastra deploy --env ${dirArg}` : '';\n  throw new Error(`Directory not found: ${dirArg}.${hint}`);\n}\n","sourceCodeStart":3,"sourceCodeEnd":23,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/deploy/validate-dir.ts#L3-L23","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","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."],"exampleFix":"// before (misread as a directory)\n$ mastra deploy staging\nError: Directory not found: staging. Did you mean: mastra deploy --env staging\n// after\n$ mastra deploy --env staging","handlingStrategy":"validation","validationCode":"import { stat } from 'node:fs/promises';\nconst target = dirArg ?? process.cwd();\nif (!(await stat(target).catch(() => null))?.isDirectory()) {\n  throw new Error(`Not a directory: ${target}. For named environments use: mastra deploy --env ${dirArg}`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["cli","filesystem","argument-validation","deploy"],"backgroundTag":"invalid-cli-argument","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}