mastra-ai/mastra · error

GitHub source control request failed: ${res.status}

Error message

GitHub source control request failed: ${res.status}

What it means

The GitHub storage provider's request helper wraps every HTTP call; when the response status is not OK it extracts a JSON 'detail' if available and throws 'GitHub source control request failed: <status>'. All provider operations (capabilities, file listing, history, change requests) funnel through it, so any GitHub API error surfaces here.

Source

Thrown at packages/core/src/storage/providers/github.ts:122

    const res = await this.fetch(`${this.endpoint}/v1/server/source-storage/github${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${this.token}`,
        Accept: 'application/json',
        'Content-Type': 'application/json',
        ...init?.headers,
      },
    });

    if (!res.ok) {
      let detail = `GitHub source control request failed: ${res.status}`;
      try {
        const body = (await res.json()) as BrokerErrorResponse;
        detail = body.detail ?? detail;
      } catch {
        // Ignore non-JSON error bodies.
      }
      throw new Error(detail);
    }

    return (await res.json()) as T;
  }
}

export function createGitHubSourceControlProviderFromEnv(
  env: Record<string, string | undefined> = process.env,
  defaults?: { pathPrefix?: string },
): GitHubSourceControlProvider | undefined {
  if (env.MASTRA_SOURCE_PROVIDER !== 'github') return undefined;

  const endpoint = env.MASTRA_SOURCE_PROVIDER_ENDPOINT ?? env.MASTRA_SHARED_API_URL ?? env.MASTRA_CLOUD_API_ENDPOINT;
  const token = env.MASTRA_PLATFORM_ACCESS_TOKEN ?? env.MASTRA_CLOUD_ACCESS_TOKEN;

  if (!endpoint || !token) return undefined;

  return new GitHubSourceControlProvider({

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect the status code and message detail; verify the configured token with `gh auth status` or a GET /user call.
2. Fix repository configuration (owner/repo/branch) and confirm the token has the required scopes.
3. Respect rate limits: add backoff/retry on 429 and 5xx, honoring the Retry-After header.

Example fix

// before
const files = await githubStorage.files('/'); // throws on 404 silently handled upstream
// after
try {
  const files = await githubStorage.files('/');
} catch (e) {
  if (String(e.message).includes('403')) {
    console.error('Check GitHub token scopes and rate limits');
  }
  throw e;
}

// Pre-flight: verify token and repo access
const res = await fetch('https://api.github.com/repos/' + owner + '/' + repo, {
  headers: { Authorization: `Bearer ${token}` }
});
if (!res.ok) throw new Error(`GitHub pre-flight failed: ${res.status}`);

try {
  const files = await githubStorage.files(path);
} catch (e) {
  const m = /failed: (\d{3})/.exec(String(e.message));
  if (m && (m[1] === '429' || m[1].startsWith('5'))) {
    await backoff(); // retry transient failures
  } else throw e; // 401/403/404 are configuration errors
}

When it happens

Trigger: Any API call to GitHub returning a non-2xx status: 401/403 (bad or expired token, missing scopes), 404 (repo/branch/path not found), 422 (bad ref or payload), 429/5xx (rate limit or GitHub outage).

Common situations: GITHUB_TOKEN missing scopes (repo/content permissions); token expired or belonging to a revoked app; wrong repo owner/name configured; hitting secondary rate limits during bulk history reads.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• GitHub OAuth token exchange failed: ${res.status}
• Slack OAuth HTTP error: ${tokenResponse.status} ${tokenRespo
• Failed to stream background tasks: ${response.statusText}
• Failed to stream agent builder action: ${response.statusText
• Failed to observe agent builder action stream: ${response.st

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