mastra-ai/mastra · error · MaterializeError

gh-missing

gh-missing

Error message

The GitHub CLI (gh) is not installed in the sandbox. The sandbox template must include gh to open pull requests.

What it means

assertGhAvailable runs `gh --version` before any PR creation; a non-zero exit throws MaterializeError('gh-missing'). The library checks explicitly so a missing GitHub CLI produces an actionable message naming the sandbox template requirement, rather than a confusing failure later in `gh pr create`.

Source

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

  title: string;
  /** PR body (optional). */
  body?: string;
}

export interface CreatePullRequestResult {
  /** The PR URL parsed from `gh pr create` stdout. */
  url: string;
}

/**
 * Preflight that `gh` is installed in the sandbox. Only called on the PR path so
 * a missing `gh` never blocks clone/open. Surfaces an actionable error naming
 * the sandbox template requirement.
 */
async function assertGhAvailable(sandbox: ExecutableSandbox): Promise<void> {
  const version = await sh(sandbox, 'gh --version');
  if (version.exitCode !== 0) {
    throw new MaterializeError(
      'The GitHub CLI (gh) is not installed in the sandbox. The sandbox template must include gh to open pull requests.',
      'gh-missing',
    );
  }
}

/** Match the first GitHub PR URL in `gh pr create` output. */
function parsePullRequestUrl(stdout: string): string | undefined {
  const match = stdout.match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/);
  return match?.[0];
}

/**
 * Open a pull request from inside the sandbox via `gh pr create`. The token is
 * passed only through a per-invocation `GH_TOKEN` env scoped to the single `gh`
 * process (never persisted), all arguments are shell-quoted, and the resulting
 * PR URL is parsed from stdout.
 *

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add gh to the sandbox template image (apt/brew install gh or official image)
2. Verify with `gh --version` inside the sandbox before opening PRs
3. Check PATH in the sandbox exec environment includes gh's install location
4. Use a newer version of the sandbox template that bundles gh

Example fix

// before (sandbox template)
FROM ubuntu:22.04  # no gh
// after
FROM ubuntu:22.04
RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
  && apt-get update && apt-get install -y gh

const v = await sh(sandbox, 'gh --version');
if (v.exitCode !== 0) throw new Error('sandbox template must include gh before opening PRs');

try {
  await createPullRequest(sandbox, workdir, args);
} catch (e) {
  if (e instanceof MaterializeError && e.code === 'gh-missing') {
    throw new Error('Rebuild sandbox template with gh installed; cannot open PR.');
  }
  throw e;
}

When it happens

Trigger: Calling createPullRequest against a sandbox whose image does not include the `gh` binary, or where gh exists but fails to execute (broken install, incompatible arch).

Common situations: Custom/minimal sandbox templates without gh; older sandbox images predating the gh requirement; PATH not including /usr/local/bin in the exec environment.

Related errors

• execa is not available in Cloudflare Workers
• Sandbox provider "${sandbox.provider}" does not support netw
• Sandbox provider "${sandbox.provider}" did not expose a publ
• Woke sandbox but the Mastra server did not become healthy at
• createSandboxProxy requires an Edge Config connection string

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