mastra-ai/mastra · error

Linear capabilities require an OAuth connection.

Error message

Linear capabilities require an OAuth connection.

What it means

Linear capabilities authenticate via OAuth only; `requireLinearConnection` is called before executing capability operations and throws when the supplied `IntegrationConnection` has a `type` other than 'oauth' (e.g. 'api-key', 'webhook', or none). The library refuses to proceed because non-OAuth credentials cannot provide the scopes Linear capabilities need.

Source

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

  if (!cursor) return {};
  if (sourceIds.length === 1) return { [sourceIds[0]!]: cursor };
  try {
    const parsed = JSON.parse(cursor) as unknown;
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error();
    return parsed as Record<string, string | null>;
  } catch {
    throw new Error('Linear cursor is invalid.');
  }
}

function encodeCursor(state: Record<string, string | null>, sourceIds: string[]): string {
  if (sourceIds.length === 1) return state[sourceIds[0]!]!;
  return JSON.stringify(state);
}

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

function isNotFound(error: unknown): boolean {
  return error instanceof PlatformApiError && error.status === 404;
}

function optionalPositiveIntegerEnv(name: string): number | undefined {
  const value = process.env[name]?.trim();
  if (!value) return undefined;
  const parsed = Number(value);
  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
    throw new Error(`${name} must be a positive integer.`);
  }
  return parsed;
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Complete the Linear OAuth flow and pass the resulting oauth connection to the capability call.
2. Check `connection.type === 'oauth'` before invoking capabilities and surface a re-auth prompt otherwise.
3. Ensure connection resolution looks up the Linear integration's connection, not another integration's.
4. If a stored connection has the wrong type, delete it and re-connect rather than editing the type field.

Example fix

// before
runCapability({ connection: getStoredConnection('linear-api-key') });
// after
const conn = getStoredConnection('linear');
if (conn.type !== 'oauth') throw new Error('Re-authorize Linear via OAuth');
runCapability({ connection: conn });

function ensureLinearOauth(connection: IntegrationConnection): void {
  if (connection.type !== 'oauth') {
    throw new Error(`Linear requires an OAuth connection (got: ${connection.type}). Re-authorize Linear.`);
  }
}

function isOauthConnection(c: IntegrationConnection): c is IntegrationConnection & { type: 'oauth' } {
  return c.type === 'oauth';
}

try {
  await runLinearCapability({ connection });
} catch (err) {
  if (err instanceof Error && err.message === 'Linear capabilities require an OAuth connection.') {
    return promptReauthorization('linear');
  }
  throw err;
}

When it happens

Trigger: Invoking a Linear capability (project sync, issue operations) while passing a connection object created with `type: 'api-key'` or similar, or a connection resolved from a different integration's credential store.

Common situations: Teams that previously used a Linear API key integration switching to the platform integration without re-authorizing OAuth; reusing a shared connection object across integrations; connection record in storage migrated with the wrong type field.

Related errors

• Linear capabilities require an OAuth connection.
• Redirect URI is required for SSO login
• Google client ID is required. Provide it in the options or s
• Redirect URI is required for Google SSO. Set GOOGLE_REDIRECT
• Google Workspace Directory authentication is not configured.

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