mastra-ai/mastra · error · MaterializeError

git-missing

git-missing

Error message

git is not installed in the sandbox. The sandbox template must include git.

What it means

As a preflight step, materializeRepo runs `git --version` inside the sandbox; a non-zero exit means the sandbox image lacks git, so materialization cannot proceed and throws this MaterializeError with code git-missing. The library requires the sandbox template to include git as part of its contract.

Source

Thrown at mastracode/factory/src/integrations/github/sandbox.ts:257

  const repo = repoInfo.repoFullName;

  // 0. Defense in depth: never build a git command from values that aren't
  // strictly shaped, even if a malformed row reached the DB. Inputs are also
  // validated at the route boundary before storage.
  if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) {
    throw new MaterializeError(`Refusing to materialize: invalid repo full name '${repo}'.`, 'clone-failed');
  }
  if (!/^[A-Za-z0-9_./-]+$/.test(repoInfo.defaultBranch)) {
    throw new MaterializeError(
      `Refusing to materialize: invalid default branch '${repoInfo.defaultBranch}'.`,
      'clone-failed',
    );
  }

  // 1. Preflight: git must be installed in the sandbox template.
  const gitVersion = await sh(sandbox, 'git --version');
  if (gitVersion.exitCode !== 0) {
    throw new MaterializeError(
      'git is not installed in the sandbox. The sandbox template must include git.',
      'git-missing',
    );
  }

  const authUrl = tokenUrl(repo, token);

  // The DB's `materializedAt` can drift from disk in both directions: a fresh
  // binding row over an already-populated workdir (local dev DB resets,
  // repaired rows, earlier flows) must pull instead of failing `git clone` on
  // the non-empty directory, and a stale `materializedAt` over an empty
  // sandbox (an expired/recreated VM whose disk was wiped) must re-clone
  // instead of running `git -C <workdir>` against a directory that no longer
  // exists. Disk is the source of truth: detect the checkout instead of
  // trusting the row.
  const alreadyMaterialized = await hasExistingCheckout(sandbox, workdir, repo);

  let tokenInRemote = false;

View on GitHub (pinned to 75dd419e61)

Solutions

Add git to the sandbox template image (e.g. `apt-get update && apt-get install -y git` or the alpine equivalent) and rebuild.
Verify inside the sandbox with `git --version` to confirm PATH resolves correctly.
Pin to a sandbox template known to include git (the one the library is normally paired with).
If git was intentionally removed, restore it — no fallback clone path exists.

Example fix

// before (Dockerfile)
FROM node:22-slim
// after
FROM node:22-slim
RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*

Defensive patterns

Strategy: validation

Validate before calling

const probe = await sh(sandbox, 'git --version');
if (probe.exitCode !== 0) throw new Error('sandbox template is missing git; rebuild the image before materializing');

Try / catch

try {
  await materializeRepo(options);
} catch (err) {
  if (err instanceof MaterializeError && err.code === 'git-missing') {
    throw new Error(`Sandbox template '${sandboxRow.templateId}' lacks git. Rebuild the image with git installed.`, { cause: err });
  }
  throw err;
}

Prevention

Include git in every sandbox template Dockerfile and assert it in the image build CI.
Run a post-build smoke check (`git --version`) on sandbox images.
Pin sandbox templates so slimmed images can't silently drop git.
Document git as a hard requirement of the sandbox contract.

When it happens

Trigger: materializeRepo() invoked against a sandbox created from a template/image that doesn't install git (minimal distro images, custom Dockerfiles without `apt-get install git`, broken PATH in the sandbox).

Common situations: Switching to a slimmer sandbox base image for cost/speed, a template regression after a Dockerfile refactor, or an offline/air-gapped sandbox where git was stripped.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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