What causes "GitHub capabilities require a GitHub connection." in mastra-ai/mastra?

Create or link a GitHub connection of type 'app-installation' (GitHub App) or 'oauth' for the org

GitHub capabilities require a GitHub connection.

Error message

GitHub capabilities require a GitHub connection.

What it means

Thrown by requireGithubConnection when an IntegrationConnection is neither type 'app-installation' nor 'oauth'. GitHub capabilities can only execute against a GitHub-backed connection; any other connection type (or a connection from a different provider) is rejected up front.

Source

Thrown at mastracode/factory/src/integrations/platform/github/integration.ts:1544

    commitId: review.commitId,
    submittedAt: review.submittedAt,
  };
}

function parseReviewComment(comment: GithubReviewComment): ReviewComment {
  return {
    ...parseComment(comment),
    path: comment.path,
    line: comment.line,
    side: comment.side?.toLowerCase() as 'left' | 'right' | null,
    commitId: comment.commitId,
    replyToId: comment.replyToId === null ? null : String(comment.replyToId),
  };
}

function requireGithubConnection(connection: IntegrationConnection): void {
  if (connection.type !== 'app-installation' && connection.type !== 'oauth') {
    throw new Error('GitHub capabilities require a GitHub connection.');
  }
}

function requireSingleSource(sourceIds: string[], message: string): string {
  if (sourceIds.length !== 1) throw new Error(message);
  return sourceIds[0]!;
}

function requireSource(sourceId: string | undefined, message: string): string {
  if (!sourceId) throw new Error(message);
  return sourceId;
}

function normalizeLabels(labels: string[] | undefined): string[] {
  return [...new Set((labels ?? []).map(label => label.trim()).filter(Boolean))];
}

function parsePositiveCursor(cursor: string | undefined): number {

View on GitHub (pinned to 75dd419e61)

Solutions

Create or link a GitHub connection of type 'app-installation' (GitHub App) or 'oauth' for the org
Verify the connection row's type field in storage and correct it if it was persisted wrong
Route the request to the integration matching the connection's actual provider
Re-run the GitHub App installation or OAuth flow to establish a valid connection

Example fix

// before
const conn = { type: 'gitlab', ... }; github.capability(conn, ...);
// after
const conn = await storage.connections.get({ orgId, type: 'app-installation', provider: 'github' });
github.capability(conn, ...);

Defensive patterns

Strategy: type-guard

Type guard

function isGithubConnection(c: IntegrationConnection): c is IntegrationConnection & { type: 'app-installation' | 'oauth' } {
  return c.type === 'app-installation' || c.type === 'oauth';
}
if (!isGithubConnection(connection)) throw new Error('route to non-GitHub integration instead');

Try / catch

try {
  await github.capability(connection, ...);
} catch (err) {
  if (err instanceof Error && err.message.includes('require a GitHub connection')) {
    // route to the integration matching connection.type/provider
  } else throw err;
}

Prevention

Store provider alongside connection.type and dispatch capabilities by provider
Re-run the GitHub App install or OAuth flow for orgs missing a GitHub connection
Add a startup check that GitHub-enabled orgs have a github-typed connection
Never reuse a non-GitHub connection object for GitHub capabilities

When it happens

Trigger: Calling a GitHub capability with a connection whose type is e.g. 'token', 'pat', 'gitlab', or another non-GitHub provider type stored on the org.

Common situations: Connecting a different VCS (GitLab/Bitbucket) integration but routing calls to the GitHub capability; misconfigured connection rows where type was saved incorrectly; switching providers without updating capability routing.

Related errors

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