mastra-ai/mastra · error

Not found at ref ${ref}: ${path}

Error message

Not found at ref ${ref}: ${path}

What it means

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.

Source

Thrown at mastracode/sdk/src/agents/prompts/agent-instructions.ts:85

    for (const candidate of [`origin/${ref}`, ref]) {
      try {
        return execFileSync('git', ['-C', projectPath, 'show', `${candidate}:${rel}`], {
          encoding: 'utf-8',
          stdio: ['ignore', 'pipe', 'ignore'],
          maxBuffer: 1024 * 1024,
        });
      } catch {
        // Ref or file missing at this candidate — try the next one.
      }
    }
    return null;
  };
  return {
    ref,
    exists: path => show(path) !== null,
    read: path => {
      const content = show(path);
      if (content === null) throw new Error(`Not found at ref ${ref}: ${path}`);
      return content;
    },
  };
}

/**
 * Reader for the reactive reminder channel (AgentsMDInjector) that serves
 * paths under `projectPath` from a trusted git ref. Paths outside the project
 * fall back to the operator machine's filesystem (those are trusted); paths
 * inside the project are only ever resolved against the ref, never the
 * working tree, so an untrusted checkout cannot feed content in.
 */
export function createGitRefReminderReader(
  projectPath: string,
  ref: string,
): {
  pathExists: (path: string) => boolean;
  isDirectory: (path: string) => boolean;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the file exists at that ref: `git show <ref>:<path>` or `git ls-tree -r <ref>`
2. Use the correct ref (branch/tag/commit) that contains the file
3. Fix path typos, including exact casing relative to the repo root
4. Re-pin the reader to a newer ref if the file was added after the pinned ref

Example fix

// before
createGitRefInstructionReader({ ref: 'v1.0.0', path: 'INSTRUCTIONS.md' }); // added in v1.1
// after
createGitRefInstructionReader({ ref: 'v1.1.0', path: 'INSTRUCTIONS.md' });

const exists = reader.exists('AGENTS.md');
if (!exists) throw new Error('AGENTS.md missing at pinned ref');

null

try {
  const content = reader.read('AGENTS.md');
} catch (err) {
  if ((err as Error).message.startsWith('Not found at ref')) {
    console.error('File missing at that ref — pick a newer ref or fix the path');
  } else throw err;
}

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• pull-failed
• ENOENT: no such file or directory: ${path}
• FilesystemSkillsStorage: skill with id ${id} not found
• ${this.name}: entity with id ${id} not found
• Not a git repository: ${dir}

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