mastra-ai/mastra · warning · HTTPException

Invalid skill name "${name}". Names must start with alphanum

Error message

Invalid skill name "${name}". Names must start with alphanumeric and contain only letters, numbers, hyphens, and underscores.

What it means

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.

Source

Thrown at packages/server/src/server/handlers/skills-sh-shared.ts:91

}

// =============================================================================
// Safety validators
// =============================================================================

/**
 * Validate skill name to prevent path traversal attacks. Only allows
 * alphanumeric characters, hyphens, and underscores; must start with an
 * alphanumeric character.
 *
 * Throws an HTTP 400 on invalid input. Returns the validated name on success
 * so it can be used inline.
 */
const SKILL_NAME_REGEX = /^[a-z0-9][a-z0-9-_]*$/i;

export function assertSafeSkillName(name: string): string {
  if (!SKILL_NAME_REGEX.test(name)) {
    throw new HTTPException(400, {
      message: `Invalid skill name "${name}". Names must start with alphanumeric and contain only letters, numbers, hyphens, and underscores.`,
    });
  }
  return name;
}

/**
 * Validate that a file path is safe (no traversal, no absolute paths).
 * Prevents malicious API responses from writing files outside the skill
 * directory.
 */
export function assertSafeFilePath(filePath: string): string {
  if (filePath.startsWith('/') || filePath.startsWith('\\') || /^[a-zA-Z]:[\\/]/.test(filePath)) {
    throw new HTTPException(400, {
      message: `Invalid file path "${filePath}". Absolute paths are not allowed.`,
    });
  }
  // Normalize backslashes to forward slashes so Windows-style traversal

View on GitHub (pinned to 75dd419e61)

Solutions

1. Normalize the name to only [a-zA-Z0-9-_], replacing other characters with hyphens.
2. Ensure the first character is alphanumeric.
3. Trim whitespace and lowercase the name before sending.
4. Pre-validate client-side with the same regex before calling the API.

Example fix

// before
const name = 'My Cool Skill!';
await createSkill({ name });
// after
const name = 'My Cool Skill!'.trim().replace(/[^a-zA-Z0-9-_]+/g, '-').replace(/^[-_]+/, '');
await createSkill({ name }); // "My-Cool-Skill"

const SKILL_NAME_REGEX = /^[a-z0-9][a-z0-9-_]*$/i;
if (!SKILL_NAME_REGEX.test(name)) throw new Error(`Skill name "${name}" is invalid; use [a-zA-Z0-9-_] and start with an alphanumeric.`);

try {
  await createSkill({ name });
} catch (e) {
  if (e instanceof MastraClientError && e.status === 400 && /Invalid skill name/.test(e.message)) {
    console.error('Sanitize the name and retry:', name.replace(/[^a-zA-Z0-9-_]+/g, '-').replace(/^[-_]+/, ''));
  } else throw e;
}

When it happens

Trigger: Creating, fetching, or deleting a skill whose name starts with a hyphen/underscore, contains spaces, slashes, dots, or other special characters, or is empty.

Common situations: 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.

Related errors

• skillPath is missing SKILL.md: ${resolvedPath}
• Skill name and reference path are required
• Malformed referencePath
• Invalid skill name "${name}". Names must start with alphanum
• bad request: ${responseText}

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