{"record":{"id":"ccd3a1bd395d74d6","repo":"mastra-ai/mastra","slug":"project-name-must-be-1-214-lowercase-characters-s","errorCode":null,"errorMessage":"Project name must be 1-214 lowercase characters, start with a letter or number, and contain only letters, numbers, dots, hyphens, or underscores","messagePattern":"Project name must be 1-214 lowercase characters, start with a letter or number, and contain only letters, numbers, dots, hyphens, or underscores","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/create/command.ts","lineNumber":139,"sourceCode":"const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\\..*)?$/i;\nconst PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;\n\nexport function validateProjectName(value: string): string {\n  const projectName = value.trim();\n\n  if (\n    projectName.length < 1 ||\n    projectName.length > 214 ||\n    path.isAbsolute(projectName) ||\n    projectName.includes('/') ||\n    projectName.includes('\\\\') ||\n    projectName === '.' ||\n    projectName === '..' ||\n    projectName.endsWith('.') ||\n    !PROJECT_NAME_PATTERN.test(projectName) ||\n    WINDOWS_RESERVED_BASENAME.test(projectName)\n  ) {\n    throw new Error(\n      'Project name must be 1-214 lowercase characters, start with a letter or number, and contain only letters, numbers, dots, hyphens, or underscores',\n    );\n  }\n\n  return projectName;\n}\n\nconst NUMERIC_IDENTIFIER_PATTERN = /^\\d+$/;\n\nfunction getPrereleaseChannel(version: string): string | undefined {\n  const separator = version.indexOf('-');\n  if (separator === -1) return undefined;\n  return version\n    .slice(separator + 1)\n    .split('.')\n    .find(identifier => !NUMERIC_IDENTIFIER_PATTERN.test(identifier));\n}\n","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/create/command.ts#L121-L157","documentation":"`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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Use a lowercase name of only letters, numbers, dots, hyphens, underscores, starting alphanumeric: `my-mastra-app`","Strip path components — run the command in the target parent directory and pass just the directory name","Avoid reserved Windows device names and trailing dots","If interactive, enter a compliant name when prompted; the prompt re-validates until valid"],"exampleFix":"// before\nmastra create \"My Project v2!\"\n// after\nmastra create my-project-v2","handlingStrategy":"validation","validationCode":"const PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;\nconst WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\\..*)?$/i;\nexport function isValidProjectName(name: string): boolean {\n  const n = name.trim();\n  return n.length >= 1 && n.length <= 214 && PROJECT_NAME_PATTERN.test(n) &&\n    !WINDOWS_RESERVED.test(n) && !n.endsWith('.') && n !== '.' && n !== '..';\n}","typeGuard":"function isSafeProjectName(value: unknown): value is string {\n  return typeof value === 'string' && /^[a-z0-9][a-z0-9._-]*$/.test(value) &&\n    !value.endsWith('.') && value.length <= 214;\n}","tryCatchPattern":"try {\n  await create({ projectName });\n} catch (error) {\n  if (error instanceof Error && error.message.startsWith('Project name must be')) {\n    console.error(`\"${projectName}\" is not a valid project name; use lowercase [a-z0-9._-]`);\n  } else throw error;\n}","preventionTips":["Normalize names: slugify repo titles before passing them as projectName","Reject Windows-reserved names (CON, NUL, COM1...) up front","Never pass absolute paths or names containing / or \\","Keep names under 214 chars and without trailing dots"],"tags":["cli","validation","naming","filesystem"],"backgroundTag":"invalid-identifier-name","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}