mastra-ai/mastra · error

Path not found in skill version tree

Error message

Path not found in skill version tree: ${path}

What it means

VersionedSkillSource.stat looks up the normalized path first in the version tree's file entries, then in the derived directory set; if the path is neither a file in the tree nor an implied directory, it throws. The version tree is an immutable manifest of a published skill version, so any path not recorded in it simply does not exist for that version.

Solutions

1. Call exists(path) first to check membership in this version's tree before stat.
2. Remove any skill-directory prefix — VersionedSkillSource paths are relative to the skill root ('SKILL.md', not '<skill>/SKILL.md').
3. Verify you are reading the intended version; the file may exist in a different SkillVersionTree.
4. If the file should exist, republish the skill version including it.

Example fix

// before
await versioned.stat('my-skill/SKILL.md'); // already scoped to skill
// after
await versioned.stat('SKILL.md');

if (await versioned.exists(path)) {
  const st = await versioned.stat(path);
}

try {
  return await versioned.stat(path);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Path not found in skill version tree')) {
    return null; // treat as non-existent for this version
  }
  throw err;
}

When it happens

Trigger: Calling stat on a VersionedSkillSource with a path absent from the SkillVersionTree entries and not derivable as a parent directory of any entry — wrong filename, wrong version, or a file that exists only in a newer version.

Common situations: Reading files that exist on the live filesystem but were never published into this version; referencing a path with a leading skill-dir prefix when the source is already scoped to one skill; stale paths after republishing a version that dropped files.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Directory not found in skill version tree
• File not found in skill version tree
• Directory not found in composite skill source
• ENOENT: no such file or directory
• File not found in composite skill source

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

Appendix: source

Thrown at packages/core/src/workspace/skills/versioned-skill-source.ts:103

        size: entry.size,
        createdAt: this.#versionCreatedAt,
        modifiedAt: this.#versionCreatedAt,
        mimeType: entry.mimeType,
      };
    }

    // Check if it's a directory
    if (this.#directories.has(normalized)) {
      return {
        name,
        type: 'directory',
        size: 0,
        createdAt: this.#versionCreatedAt,
        modifiedAt: this.#versionCreatedAt,
      };
    }

    throw new Error(`Path not found in skill version tree: ${path}`);
  }

  async readFile(path: string): Promise<string | Buffer> {
    const normalized = this.#normalizePath(path);
    const entry = this.#tree.entries[normalized];

    if (!entry) {
      throw new Error(`File not found in skill version tree: ${path}`);
    }

    const blob = await this.#blobStore.get(entry.blobHash);
    if (!blob) {
      throw new Error(`Blob not found for hash ${entry.blobHash} (file: ${path})`);
    }

    // Decode base64-encoded binary content back to Buffer
    if (entry.encoding === 'base64') {
      return Buffer.from(blob.content, 'base64');

View on GitHub (pinned to 75dd419e61)