{"record":{"id":"dedd7e1dc1ee0b2e","repo":"mastra-ai/mastra","slug":"not-found-at-ref-ref-path","errorCode":null,"errorMessage":"Not found at ref ${ref}: ${path}","messagePattern":"Not found at ref (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/agents/prompts/agent-instructions.ts","lineNumber":85,"sourceCode":"    for (const candidate of [`origin/${ref}`, ref]) {\n      try {\n        return execFileSync('git', ['-C', projectPath, 'show', `${candidate}:${rel}`], {\n          encoding: 'utf-8',\n          stdio: ['ignore', 'pipe', 'ignore'],\n          maxBuffer: 1024 * 1024,\n        });\n      } catch {\n        // Ref or file missing at this candidate — try the next one.\n      }\n    }\n    return null;\n  };\n  return {\n    ref,\n    exists: path => show(path) !== null,\n    read: path => {\n      const content = show(path);\n      if (content === null) throw new Error(`Not found at ref ${ref}: ${path}`);\n      return content;\n    },\n  };\n}\n\n/**\n * Reader for the reactive reminder channel (AgentsMDInjector) that serves\n * paths under `projectPath` from a trusted git ref. Paths outside the project\n * fall back to the operator machine's filesystem (those are trusted); paths\n * inside the project are only ever resolved against the ref, never the\n * working tree, so an untrusted checkout cannot feed content in.\n */\nexport function createGitRefReminderReader(\n  projectPath: string,\n  ref: string,\n): {\n  pathExists: (path: string) => boolean;\n  isDirectory: (path: string) => boolean;","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/agents/prompts/agent-instructions.ts#L67-L103","documentation":"createGitRefInstructionReader builds a file reader over a git ref (via `git show <ref>:<path>`). `show` returns null for missing paths; the reader's `read` converts that null into a thrown 'Not found at ref <ref>: <path>' so callers get a clear error naming the ref and path instead of a null dereference.","triggerScenarios":"`reader.read(path)` (also via gitReader/projectReader) is called for a path that does not exist at the given git ref — wrong filename, path present only on another branch, or path added after the ref was created.","commonSituations":"Pinning instructions to an old ref/tag that predates a new instruction file, typos in relative paths (case-sensitive paths), reading files from a deleted branch, or Windows/macOS case-insensitive filesystems masking case mismatches in the repo.","solutions":["Verify the file exists at that ref: `git show <ref>:<path>` or `git ls-tree -r <ref>`","Use the correct ref (branch/tag/commit) that contains the file","Fix path typos, including exact casing relative to the repo root","Re-pin the reader to a newer ref if the file was added after the pinned ref"],"exampleFix":"// before\ncreateGitRefInstructionReader({ ref: 'v1.0.0', path: 'INSTRUCTIONS.md' }); // added in v1.1\n// after\ncreateGitRefInstructionReader({ ref: 'v1.1.0', path: 'INSTRUCTIONS.md' });","handlingStrategy":"try-catch","validationCode":"const exists = reader.exists('AGENTS.md');\nif (!exists) throw new Error('AGENTS.md missing at pinned ref');","typeGuard":"null","tryCatchPattern":"try {\n  const content = reader.read('AGENTS.md');\n} catch (err) {\n  if ((err as Error).message.startsWith('Not found at ref')) {\n    console.error('File missing at that ref — pick a newer ref or fix the path');\n  } else throw err;\n}","preventionTips":["Call reader.exists() before read() when the file may be optional","Verify paths with `git ls-tree -r <ref>` when pinning refs","Prefer newer refs/commits for content added recently","Use exact path casing from the repo"],"tags":["git","filesystem","not-found"],"backgroundTag":"path-not-found-at-ref","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}