mastra-ai/mastra · error · Error

GitHub CLI is required to install GitHub plugins. Install gh

Error message

GitHub CLI is required to install GitHub plugins. Install gh and run gh auth login.

What it means

Installing plugins from GitHub requires the GitHub CLI (`gh`) for cloning/authenticated repository access. assertGithubCliAvailable runs `gh --version` non-interactively before any install work; any failure (binary missing, spawn error) becomes this single actionable error.

Source

Thrown at mastracode/sdk/src/plugins/install.ts:213

): Promise<void> {
  const child = execa(command, args, {
    ...execaOptions,
    stdout: options.onOutput ? 'pipe' : 'ignore',
    stderr: options.onOutput ? 'pipe' : 'ignore',
    cancelSignal: options.signal,
  });
  if (options.onOutput) {
    child.stdout?.on('data', options.onOutput);
    child.stderr?.on('data', options.onOutput);
  }
  await child;
}

async function assertGithubCliAvailable(githubCli: string): Promise<void> {
  try {
    await execa(githubCli, ['--version'], NON_INTERACTIVE_EXEC_OPTIONS);
  } catch {
    throw new Error('GitHub CLI is required to install GitHub plugins. Install gh and run gh auth login.');
  }
}

async function assertGithubCliAuthenticated(githubCli: string): Promise<void> {
  try {
    await execa(githubCli, ['auth', 'status'], NON_INTERACTIVE_EXEC_OPTIONS);
  } catch {
    throw new Error('GitHub CLI is not authenticated. Run gh auth login, then install the plugin again.');
  }
}

function parseGithubUrl(specifier: string): { owner: string; repo: string; repoSpec: string; ref?: string } {
  const [urlPart, ref] = specifier.split('#', 2);
  if (!urlPart) {
    throw new Error(`Invalid GitHub URL: ${specifier}`);
  }
  let url: URL;
  try {

View on GitHub (pinned to 75dd419e61)

Solutions

Install the GitHub CLI (e.g. `brew install gh`, `apt install gh`, or winget) and retry.
Verify `gh --version` works in the same shell/environment running the SDK.
Fix PATH so the gh binary directory is included for the process environment.
If the plugin is available locally, install it via a local path instead of a GitHub specifier.

Example fix

// before
mastra plugin install github:owner/repo   # gh missing

// after
brew install gh && gh auth login
mastra plugin install github:owner/repo

Defensive patterns

Strategy: try-catch

Validate before calling

import { execFileSync } from 'node:child_process';
export function isGhInstalled(): boolean {
  try { execFileSync('gh', ['--version'], { stdio: 'ignore' }); return true; }
  catch { return false; }
}
if (!isGhInstalled()) throw new Error('Install the GitHub CLI before installing GitHub plugins');

Try / catch

try {
  await installGithubPlugin(spec);
} catch (err) {
  if (err instanceof Error && err.message.includes('GitHub CLI is required')) {
    console.error('Install gh (https://cli.github.com) and ensure it is on PATH.');
  }
  throw err;
}

Prevention

Install gh in dev containers/CI base images as a standard dependency.
Check `which gh` in bootstrap scripts before running installs.
Document gh as a prerequisite alongside Node in the project README.

When it happens

Trigger: Calling installGithubPlugin when `execa(githubCli, ['--version'])` throws — typically because `gh` is not installed or not on PATH of the process environment.

Common situations: Fresh machines/CI images without gh; gh installed via snap/desktop app but not on PATH; restricted PATH in systemd or GUI-launched processes; wrong executable name override in config.

Related errors

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