{"record":{"id":"4ec897b1804ba850","repo":"mastra-ai/mastra","slug":"invalid-skill-name-name-names-must-start-wit","errorCode":null,"errorMessage":"Invalid skill name \"${name}\". Names must start with alphanumeric and contain only letters, numbers, hyphens, and underscores.","messagePattern":"Invalid skill name \"(.+?)\"\\. Names must start with alphanumeric and contain only letters, numbers, hyphens, and underscores\\.","errorType":"validation","errorClass":"HTTPException","httpStatus":400,"severity":"warning","filePath":"packages/server/src/server/handlers/skills-sh-shared.ts","lineNumber":91,"sourceCode":"}\n\n// =============================================================================\n// Safety validators\n// =============================================================================\n\n/**\n * Validate skill name to prevent path traversal attacks. Only allows\n * alphanumeric characters, hyphens, and underscores; must start with an\n * alphanumeric character.\n *\n * Throws an HTTP 400 on invalid input. Returns the validated name on success\n * so it can be used inline.\n */\nconst SKILL_NAME_REGEX = /^[a-z0-9][a-z0-9-_]*$/i;\n\nexport function assertSafeSkillName(name: string): string {\n  if (!SKILL_NAME_REGEX.test(name)) {\n    throw new HTTPException(400, {\n      message: `Invalid skill name \"${name}\". Names must start with alphanumeric and contain only letters, numbers, hyphens, and underscores.`,\n    });\n  }\n  return name;\n}\n\n/**\n * Validate that a file path is safe (no traversal, no absolute paths).\n * Prevents malicious API responses from writing files outside the skill\n * directory.\n */\nexport function assertSafeFilePath(filePath: string): string {\n  if (filePath.startsWith('/') || filePath.startsWith('\\\\') || /^[a-zA-Z]:[\\\\/]/.test(filePath)) {\n    throw new HTTPException(400, {\n      message: `Invalid file path \"${filePath}\". Absolute paths are not allowed.`,\n    });\n  }\n  // Normalize backslashes to forward slashes so Windows-style traversal","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/skills-sh-shared.ts#L73-L109","documentation":"A 400 validation error from `assertSafeSkillName`, which enforces the pattern /^[a-z0-9][a-z0-9-_]*$/i on skill names before the server touches the filesystem or upstream APIs. It blocks names that could enable path injection or break tooling conventions.","triggerScenarios":"Creating, fetching, or deleting a skill whose name starts with a hyphen/underscore, contains spaces, slashes, dots, or other special characters, or is empty.","commonSituations":"Deriving a skill name from user input without sanitizing; using a display title like \"My Cool Skill\" as the name; names with dots (e.g. \"my.skill\"); leading dashes from CLI flag parsing.","solutions":["Normalize the name to only [a-zA-Z0-9-_], replacing other characters with hyphens.","Ensure the first character is alphanumeric.","Trim whitespace and lowercase the name before sending.","Pre-validate client-side with the same regex before calling the API."],"exampleFix":"// before\nconst name = 'My Cool Skill!';\nawait createSkill({ name });\n// after\nconst name = 'My Cool Skill!'.trim().replace(/[^a-zA-Z0-9-_]+/g, '-').replace(/^[-_]+/, '');\nawait createSkill({ name }); // \"My-Cool-Skill\"","handlingStrategy":"validation","validationCode":"const SKILL_NAME_REGEX = /^[a-z0-9][a-z0-9-_]*$/i;\nif (!SKILL_NAME_REGEX.test(name)) throw new Error(`Skill name \"${name}\" is invalid; use [a-zA-Z0-9-_] and start with an alphanumeric.`);","typeGuard":null,"tryCatchPattern":"try {\n  await createSkill({ name });\n} catch (e) {\n  if (e instanceof MastraClientError && e.status === 400 && /Invalid skill name/.test(e.message)) {\n    console.error('Sanitize the name and retry:', name.replace(/[^a-zA-Z0-9-_]+/g, '-').replace(/^[-_]+/, ''));\n  } else throw e;\n}","preventionTips":["Sanitize user-derived names with a slugify step before calling the API.","Enforce the same regex in client forms for immediate feedback.","Trim and lowercase names consistently across environments."],"tags":["validation","http-400","skills"],"backgroundTag":"invalid-input-validation","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}