mastra-ai/mastra · error

Invalid skill metadata in ${filePath}: ${validation.errors.j

Error message

Invalid skill metadata in ${filePath}:
${validation.errors.join('\n')}

What it means

Thrown by WorkspaceSkillsImpl when a SKILL.md file's frontmatter metadata fails validation on load (enabled via #validateOnLoad). Validation also reports token/line-count warnings, but errors mean the skill definition is structurally invalid and cannot be loaded. The message includes the file path and each validation error joined by newlines.

Source

Thrown at packages/core/src/workspace/skills/workspace-skills.ts:1197

    // Extract required fields
    // Get skill directory path (parent of SKILL.md) - needed for SkillMetadata
    const skillPath = this.#getParentPath(filePath);

    const metadata: SkillMetadata = {
      name: frontmatter.name,
      path: skillPath,
      description: frontmatter.description,
      license: frontmatter.license,
      compatibility: frontmatter.compatibility,
      'user-invocable': frontmatter['user-invocable'],
      metadata: frontmatter.metadata,
    };

    // Validate if enabled (includes token/line count warnings)
    if (this.#validateOnLoad) {
      const validation = this.#validateSkillMetadata(metadata, dirName, body);
      if (!validation.valid) {
        throw new Error(`Invalid skill metadata in ${filePath}:\n${validation.errors.join('\n')}`);
      }
    }

    // Discover reference, script, and asset files (parallel — independent subdirs)
    const [references, scripts, assets] = await Promise.all([
      this.#discoverFilesInSubdir(skillPath, 'references'),
      this.#discoverFilesInSubdir(skillPath, 'scripts'),
      this.#discoverFilesInSubdir(skillPath, 'assets'),
    ]);

    // Build indexable content (instructions + references)
    const indexableContent = await this.#buildIndexableContent(body, skillPath, references);

    return {
      ...metadata,
      instructions: body,
      source,
      references,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the validation errors listed in the message and fix the SKILL.md frontmatter fields at the given filePath
2. Ensure required metadata fields (name matching the directory, non-empty description) exist with correct types
3. Split or shorten the skill body/references if token/line-count limit errors are reported
4. Set validateOnLoad to false only if you intentionally want to skip validation (not recommended)

Example fix

// before: .mastra/skills/my-skill/SKILL.md
---
name: My Skill
desc: does things
---
// after
---
name: my-skill
description: Does things when invoked.
---

function validateSkillMd(meta) {
  const errors = [];
  if (!meta?.name) errors.push('missing name');
  if (!meta?.description) errors.push('missing description');
  if (typeof meta?.name !== 'string') errors.push('name must be a string');
  return { valid: errors.length === 0, errors };
}

function isValidSkillMetadata(m: unknown): m is { name: string; description: string } {
  return !!m && typeof m === 'object' && typeof (m as any).name === 'string' && typeof (m as any).description === 'string';
}

try {
  const skill = await skills.loadSkill(dir);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid skill metadata in')) {
    console.error('Fix SKILL.md:', e.message);
  } else throw e;
}

When it happens

Trigger: Loading a skill from a directory whose SKILL.md frontmatter is missing required fields (e.g. name/description), has fields of the wrong type, or whose body/section sizes exceed configured limits, while validateOnLoad is enabled.

Common situations: Hand-authored skill directories with typos in frontmatter keys; skills copied from other repos with older metadata formats; skills generated by tooling that omitted required fields; oversized skill bodies after heavy edits.

Related errors

• MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA
• Invalid skill "${name}": ${validation.errors.join('; ')}
• page must be >= 0
• page value too large
• SKILL.md not found in skill files

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