{"record":{"id":"bdb0033569055774","repo":"mastra-ai/mastra","slug":"file-not-found-in-skill-version-tree-path","errorCode":null,"errorMessage":"File not found in skill version tree: ${path}","messagePattern":"File not found in skill version tree: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/skills/versioned-skill-source.ts","lineNumber":111,"sourceCode":"    if (this.#directories.has(normalized)) {\n      return {\n        name,\n        type: 'directory',\n        size: 0,\n        createdAt: this.#versionCreatedAt,\n        modifiedAt: this.#versionCreatedAt,\n      };\n    }\n\n    throw new Error(`Path not found in skill version tree: ${path}`);\n  }\n\n  async readFile(path: string): Promise<string | Buffer> {\n    const normalized = this.#normalizePath(path);\n    const entry = this.#tree.entries[normalized];\n\n    if (!entry) {\n      throw new Error(`File not found in skill version tree: ${path}`);\n    }\n\n    const blob = await this.#blobStore.get(entry.blobHash);\n    if (!blob) {\n      throw new Error(`Blob not found for hash ${entry.blobHash} (file: ${path})`);\n    }\n\n    // Decode base64-encoded binary content back to Buffer\n    if (entry.encoding === 'base64') {\n      return Buffer.from(blob.content, 'base64');\n    }\n\n    return blob.content;\n  }\n\n  async readdir(path: string): Promise<SkillSourceEntry[]> {\n    const normalized = this.#normalizePath(path);\n","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/skills/versioned-skill-source.ts#L93-L129","documentation":"VersionedSkillSource.readFile requires the normalized path to be a key in the version tree's entries map; if it isn't, the file is not part of this published skill version and the error is thrown. Unlike stat, directories cannot be read, so directory paths also fail here.","triggerScenarios":"Calling readFile with a path not present in SkillVersionTree.entries — file never published, exists only in another version, path includes an extra skill-dir prefix, or casing/whitespace mismatch.","commonSituations":"Reading 'references/api.md' that was added after this version was published; agents accessing files listed in a newer SKILL.md while pinned to an older version; case-sensitive lookups failing on 'Readme.md' vs 'readme.md'.","solutions":["Check the exact path exists via exists(path) or by inspecting the version tree entries.","Ensure paths are relative to the skill root with no leading slash or skill-directory prefix.","Point the source at the correct skill version tree that contains the file.","Republish the skill so the desired file is included in the version."],"exampleFix":"// before\nawait versioned.readFile('/references/api.md'); // leading slash + maybe absent\n// after\nawait versioned.readFile('references/api.md');","handlingStrategy":"validation","validationCode":"if (!(await versioned.exists(path))) {\n  return null;\n}\nconst content = await versioned.readFile(path);","typeGuard":null,"tryCatchPattern":"try {\n  return await versioned.readFile(path);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('File not found in skill version tree')) {\n    return fallbackContent(path); // e.g. prompt the agent the file is unavailable\n  }\n  throw err;\n}","preventionTips":["Derive file paths from the version tree entries, not the live filesystem.","Match exact casing; lookups are key-based on tree entries.","Republish versions after adding new files agents depend on."],"tags":["filesystem","skills","versioning","not-found"],"backgroundTag":"file-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}