mastra-ai/mastra · error

Linear capabilities require an OAuth connection.

Error message

Linear capabilities require an OAuth connection.

What it means

`getLinearAccessToken` enforces that a Linear integration connection must be of type `oauth` before any Linear capability runs; non-OAuth connections (e.g. api-key or no connection) carry no usable `accessToken` for the GraphQL API. It is a precondition check guarding all Linear operations that need the token.

Source

Thrown at mastracode/factory/src/integrations/linear/integration.ts:1025

  /**
   * Org-scoped agent tools: issue detail + comment tools for sessions whose
   * project belongs to an org with an active Linear connection.
   */
  async agentTools(args: { requestContext: RequestContext }): Promise<IntegrationTools> {
    return buildLinearAgentTools({ requestContext: args.requestContext, linear: this });
  }

  /** Non-secret config snapshot for system diagnostics/startup logs. */
  diagnostics(): Record<string, unknown> {
    return {
      oauthAppConfigured: true,
    };
  }
}

function getLinearAccessToken(connection: IntegrationConnection): string {
  if (connection.type !== 'oauth') {
    throw new Error('Linear capabilities require an OAuth connection.');
  }
  return connection.accessToken;
}

function linearIssueToIntakeIssue(issue: Omit<LinearIssue, 'projectId'>): IntakeIssue {
  return {
    id: issue.id,
    identifier: issue.identifier,
    title: issue.title,
    url: issue.url,
    author: issue.creator,
    state: issue.state,
    stateType: issue.stateType,
    priority: issue.priorityLabel,
    assignee: issue.assignee,
    source: issue.team,
    labels: issue.labels,
    commentCount: null,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Reconnect the Linear integration through the proper OAuth flow so a connection of `type: 'oauth'` with an `accessToken` is stored.
2. Inspect the stored `IntegrationConnection` and confirm `type === 'oauth'` and `accessToken` is present before invoking Linear capabilities.
3. If you intended key-based auth, migrate to OAuth — this integration only supports OAuth tokens.
4. Fix code/tests that construct or pass the wrong connection object to the integration.

Example fix

// before
useIntegration('linear', { type: 'api_key', apiKey: process.env.LINEAR_API_KEY })
// after
const conn = await getConnection('linear');
if (conn?.type !== 'oauth' || !conn.accessToken) {
  await startOAuthConnect('linear'); // complete the Linear OAuth handshake
}
await useIntegration('linear', conn);

function canUseLinear(conn: IntegrationConnection | undefined): boolean {
  return !!conn && conn.type === 'oauth' && typeof conn.accessToken === 'string' && conn.accessToken.length > 0;
}
if (!canUseLinear(connection)) await startOAuthConnect('linear');

function isOAuthConnection(c: IntegrationConnection): c is IntegrationConnection & { type: 'oauth'; accessToken: string } {
  return c.type === 'oauth' && typeof c.accessToken === 'string' && c.accessToken.length > 0;
}

try {
  await integration.runCapability(cap, connection);
} catch (e) {
  if (e.message.includes('require an OAuth connection')) {
    await startOAuthConnect('linear'); // prompt user to (re)connect via OAuth
    const conn = await getConnection('linear');
    await integration.runCapability(cap, conn);
  } else throw e;
}

When it happens

Trigger: Invoking any LinearIntegration capability (fetch/update issues, add comments) with a connection whose `type` is not `'oauth'` — e.g. the integration was configured as a generic API-key connection, the connection record is a placeholder/disconnected stub, or code passed the wrong connection object to the integration.

Common situations: Completing the Linear flow with a non-OAuth provider by mistake; storing a Linear API key in a connection record instead of doing the OAuth handshake; a migration/import produced connections with legacy types; tests passing a mock connection without `type: 'oauth'`.

Related errors

• Redirect URI is required for SSO login
• Linear capabilities require an OAuth connection.
• Anthropic API key credential is configured, but OAuth is req
• State token has expired
• Clerk JWKS URI, secret key and publishable key are required,

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