mastra-ai/mastra · error · Error

A file or directory named "${projectName}" already exists. P

Error message

A file or directory named "${projectName}" already exists. Please choose a different name.

What it means

`create` in packages/cli/src/commands/create/create.ts:244 checks `fsSync.existsSync(targetPath)` for the resolved project directory and throws if any file or directory already occupies it. This prevents clobbering existing content — the scaffolder only writes into a fresh path. Note the interactive prompt validates this too, but the explicit projectName CLI argument path only hits this throw.

Source

Thrown at packages/cli/src/commands/create/create.ts:245

  projectName: string | undefined,
  options: CreateCommandOptions,
  dependencies: Pick<CreateOptions, 'analytics' | 'resolveVersionTag'> = {},
): Promise<void> {
  const normalized = normalizeCreateCommandOptions(projectName, options);
  await create({ ...normalized, ...dependencies });
}

export const create = async (args: CreateOptions): Promise<void> => {
  const options = normalizeDirectCreateOptions(args);
  const mode = validateCreateOptionConflicts(options);
  const invocationCwd = process.cwd();

  const rawProjectName = options.projectName ?? (await promptForProjectName());
  const projectName = validateProjectName(rawProjectName);
  const targetPath = path.resolve(invocationCwd, projectName);

  if (fsSync.existsSync(targetPath)) {
    throw new Error(`A file or directory named "${projectName}" already exists. Please choose a different name.`);
  }

  const analytics = args.analytics ?? getAnalytics();
  let llmProvider = options.llmProvider;
  let llmApiKey = options.llmApiKey;
  let providerSelectionMethod: 'cli_args' | 'interactive' | undefined;
  let observabilityEnabled = false;
  let platformSetupController: AbortController | undefined;
  let platformSetupPromise: Promise<PlatformSetupResult> | undefined;

  if (mode === 'managed') {
    const providerProvidedByCli = llmProvider !== undefined;
    if (llmProvider) {
      providerSelectionMethod = 'cli_args';
    } else {
      llmProvider = await promptForProvider();
      providerSelectionMethod = 'interactive';
    }

View on GitHub (pinned to 75dd419e61)

Solutions

Choose a different project name: `mastra create my-app-2`
Remove or rename the existing file/directory if it's no longer needed: `mv my-app my-app.bak`
Inspect the existing path first (`ls my-app`) to confirm it's safe to delete
Run the command from a different parent directory

Example fix

// before
mastra create my-app   # ./my-app exists
// after
rm -rf my-app          # or rename it
mastra create my-app

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'node:fs';
import path from 'node:path';
const target = path.resolve(process.cwd(), projectName);
if (fs.existsSync(target)) {
  throw new Error(`"${projectName}" already exists in ${process.cwd()}; pick another name or remove it`);
}

Try / catch

try {
  await create({ projectName });
} catch (error) {
  if (error instanceof Error && error.message.includes('already exists')) {
    const alt = `${projectName}-${Date.now()}`;
    console.error(`Path taken; retrying as ${alt}`);
    await create({ projectName: alt });
  } else throw error;
}

Prevention

Check fs.existsSync on the target path before invoking create
Use unique, timestamped names in CI to avoid rerun collisions
Clean up partially created projects before re-running create
Note the interactive prompt also blocks existing directories — the throw mainly guards the CLI-arg path

When it happens

Trigger: `mastra create my-app` when ./my-app already exists (previous scaffold, empty dir, or stray file); running create twice in the same directory; a file (not dir) with the target name exists.

Common situations: Re-running a failed/partial create after cleanup didn't remove the folder; colliding with a common name like `app` or `server` in a crowded workspace; leftover staging output from an interrupted run.

Related errors

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