mastra-ai/mastra · error

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

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.

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)

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

• File not found in skill version tree: ${path}
• Directory not found in skill version tree: ${path}
• ENOENT: no such file or directory: ${path}
• FilesystemSkillsStorage: skill with id ${id} not found
• File not found in composite skill source: ${path}

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