mastra-ai/mastra · error

Unable to read workspace diff

Error message

Unable to read workspace diff

What it means

The bounded `git diff HEAD -- <pathspec>` returned a non-zero exit code. The function surfaces git's stderr (falling back to a generic message) because no diff could be produced — typically a bad pathspec, a path outside the repo, or a corrupt/unavailable git state in the sandbox workdir.

Source

Thrown at mastracode/factory/src/routes/fs.ts:722

  const safePreviousPath = previousPath ? assertRelativePath(previousPath, 'previousPath') : undefined;
  const handle = await sessionSandbox(session);
  if (!handle) throw new Error('Session workspace is not available');

  const pathspecs = safePreviousPath ? [safePreviousPath, safePath] : [safePath];
  let result = await executeBoundedGitDiff(handle.sandbox, [
    '--literal-pathspecs',
    '-C',
    handle.workdir,
    'diff',
    '--find-renames',
    '--no-ext-diff',
    '--no-color',
    '--unified=3',
    'HEAD',
    '--',
    ...pathspecs,
  ]);
  if (result.exitCode !== 0) throw new Error(result.stderr || 'Unable to read workspace diff');

  if (!result.stdout) {
    const untracked = await handle.sandbox.executeCommand(
      'git',
      ['--literal-pathspecs', '-C', handle.workdir, 'ls-files', '--others', '--exclude-standard', '--', safePath],
      { timeout: 30_000 },
    );
    if (untracked.exitCode === 0 && untracked.stdout.trim()) {
      result = await executeBoundedGitDiff(
        handle.sandbox,
        [
          '-C',
          handle.workdir,
          'diff',
          '--no-index',
          '--no-ext-diff',
          '--no-color',
          '--unified=3',

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Read the surfaced stderr (the thrown message) to identify the exact git failure and fix the pathspec accordingly.
  2. Ensure the workspace has a valid HEAD (initial commit exists) before diffing; commit or initialize the repo if needed.
  3. Check the session workdir is a real git repository with readable .git metadata.
  4. Retry with an exact, relative path (assertRelativePath-normalized) without special characters.

Example fix

// before
await getSessionWorkspaceDiff(session, '../outside/file.ts');
// after
const ok = await stat(session, 'src/index.ts'); // confirm path exists & is inside workspace
if (ok) await getSessionWorkspaceDiff(session, 'src/index.ts');
Defensive patterns

Strategy: try-catch

Validate before calling

const handle = await sessionSandbox(session);
const stat = await handle.filesystem.stat(path);
const headOk = (await handle.sandbox.executeCommand('git', ['--literal-pathspecs', '-C', handle.workdir, 'rev-parse', 'HEAD'], { timeout: 30_000 })).exitCode === 0;
const ready = stat.type === 'file' && headOk;

Type guard

function diffablePath(p: string): boolean {
  return !p.includes('..') && !p.startsWith('/') && p.trim() !== '';
}

Try / catch

try {
  const diff = await getSessionWorkspaceDiff(session, path);
} catch (e) {
  if (e instanceof Error && e.message.includes('fatal:')) {
    // stderr surfaced by the throw — log it and fix the pathspec/repo state
    logger.error('git diff failed', { stderr: e.message, path });
  } else throw e;
}

Prevention

When it happens

Trigger: Diffing a path that doesn't match any tracked/untracked file pattern accepted by git; pathspec syntax errors; git failing in the sandbox (missing HEAD, not a repository, permission issues) with a non-zero exit.

Common situations: Typo'd or URL-encoded paths with characters git treats specially; diffing files in a workspace whose git metadata was stripped; newly created workdir without an initial commit so HEAD doesn't exist.

Related errors

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