mastra-ai/mastra · error · Error

Project name must be 1-214 lowercase characters, start with

Error message

Project name must be 1-214 lowercase characters, start with a letter or number, and contain only letters, numbers, dots, hyphens, or underscores

What it means

`validateProjectName` in packages/cli/src/commands/create/command.ts:139 enforces npm/filesystem-safe project names: 1-214 chars, lowercase, starting with a letter or digit, containing only `[a-z0-9._-]`, no absolute paths, path separators, `.`/`..`, trailing dot, or Windows reserved basenames (CON, PRN, AUX, NUL, COM1-9, LPT1-9). It throws because the resulting directory name must be a valid package name and portable across OSes.

Source

Thrown at packages/cli/src/commands/create/command.ts:139

const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
const PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;

export function validateProjectName(value: string): string {
  const projectName = value.trim();

  if (
    projectName.length < 1 ||
    projectName.length > 214 ||
    path.isAbsolute(projectName) ||
    projectName.includes('/') ||
    projectName.includes('\\') ||
    projectName === '.' ||
    projectName === '..' ||
    projectName.endsWith('.') ||
    !PROJECT_NAME_PATTERN.test(projectName) ||
    WINDOWS_RESERVED_BASENAME.test(projectName)
  ) {
    throw new Error(
      'Project name must be 1-214 lowercase characters, start with a letter or number, and contain only letters, numbers, dots, hyphens, or underscores',
    );
  }

  return projectName;
}

const NUMERIC_IDENTIFIER_PATTERN = /^\d+$/;

function getPrereleaseChannel(version: string): string | undefined {
  const separator = version.indexOf('-');
  if (separator === -1) return undefined;
  return version
    .slice(separator + 1)
    .split('.')
    .find(identifier => !NUMERIC_IDENTIFIER_PATTERN.test(identifier));
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a lowercase name of only letters, numbers, dots, hyphens, underscores, starting alphanumeric: `my-mastra-app`
2. Strip path components — run the command in the target parent directory and pass just the directory name
3. Avoid reserved Windows device names and trailing dots
4. If interactive, enter a compliant name when prompted; the prompt re-validates until valid

Example fix

// before
mastra create "My Project v2!"
// after
mastra create my-project-v2

const PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
export function isValidProjectName(name: string): boolean {
  const n = name.trim();
  return n.length >= 1 && n.length <= 214 && PROJECT_NAME_PATTERN.test(n) &&
    !WINDOWS_RESERVED.test(n) && !n.endsWith('.') && n !== '.' && n !== '..';
}

function isSafeProjectName(value: unknown): value is string {
  return typeof value === 'string' && /^[a-z0-9][a-z0-9._-]*$/.test(value) &&
    !value.endsWith('.') && value.length <= 214;
}

try {
  await create({ projectName });
} catch (error) {
  if (error instanceof Error && error.message.startsWith('Project name must be')) {
    console.error(`"${projectName}" is not a valid project name; use lowercase [a-z0-9._-]`);
  } else throw error;
}

When it happens

Trigger: `mastra create "My App"` (uppercase/spaces); `mastra create /abs/path` or `a/b`; `mastra create .`/`..`; `mastra create myproject.`; `mastra create CON` or `com1`; names with `~`, `@`, or other symbols failing PROJECT_NAME_PATTERN.

Common situations: Reusing a GitHub repo name with uppercase or special characters; passing a full path instead of a bare directory name; Windows users hitting reserved device names; copying a name with a trailing period or emoji from docs.

Related errors

• Missing required query param: ${label}
• ${label} must be relative
• ${label} escapes workspace
• Path escapes workspace
• Path is a directory

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