Slack OAuth response missing required fields (access_token,

Error message

Slack OAuth response missing required fields (access_token, bot_user_id, or team)

What it means

After Slack returned ok:true, the provider requires access_token, bot_user_id, and team.id to build a SlackInstallation. If any of these fields is missing or empty, the response is considered incomplete and unusable, so the provider throws with an explicit list of the missing fields. This guards against persisting a corrupted installation record.

Source

Thrown at channels/slack/src/provider.ts:1440

      if (!tokenResponse.ok) {
        throw new Error(`Slack OAuth HTTP error: ${tokenResponse.status} ${tokenResponse.statusText}`);
      }

      const tokenData = (await tokenResponse.json()) as {
        ok: boolean;
        error?: string;
        access_token?: string;
        bot_user_id?: string;
        team?: { id: string; name: string };
      };

      if (!tokenData.ok) {
        throw new Error(`OAuth failed: ${tokenData.error}`);
      }

      if (!tokenData.access_token || !tokenData.bot_user_id || !tokenData.team?.id) {
        throw new Error('Slack OAuth response missing required fields (access_token, bot_user_id, or team)');
      }

      // Save completed installation (encrypted)
      const installation: SlackInstallation = {
        id: pending.id,
        agentId: pending.agentId,
        ownerType: pending.ownerType ?? 'agent',
        webhookId: pending.webhookId,
        appId: pending.appId,
        clientId: pending.clientId,
        clientSecret: pending.clientSecret,
        signingSecret: pending.signingSecret,
        botToken: tokenData.access_token,
        botUserId: tokenData.bot_user_id,
        teamId: tokenData.team.id,
        teamName: tokenData.team.name ?? '',
        name: pending.name,
        description: pending.description,

View on GitHub (pinned to 75dd419e61)

Solutions

Ensure the Slack app has a bot user and the app is installed as a workspace app (bot token starts with xoxb).
Re-run the OAuth install flow after fixing the app configuration in api.slack.com/apps.
Check the requested scopes/flow — a user-token flow won't produce bot_user_id; use the bot install flow.
Inspect the raw tokenData response (log it) to confirm which field is missing and why.

Defensive patterns

Strategy: type-guard

Type guard

function hasBotTokenData(d: { ok: boolean; access_token?: string; bot_user_id?: string; team?: { id?: string } }): d is { ok: true; access_token: string; bot_user_id: string; team: { id: string } } {
  return d.ok === true && !!d.access_token && !!d.bot_user_id && !!d.team?.id;
}

Try / catch

try {
  await handleSlackOAuthCallback(req);
} catch (e) {
  if (e instanceof Error && e.message.includes('missing required fields')) {
    console.error('Slack app is not configured as a bot app; fix app settings and reinstall');
  } else throw e;
}

Prevention

Ensure the Slack app includes a bot user and bot token scopes before installing.
Don't convert app types (workspace <-> organization/user) without redoing installs.
Smoke-test the install flow in staging after any Slack app manifest change.

When it happens

Trigger: Slack's oauth.v2.access returns ok:true but omits access_token, bot_user_id, or team.id — typically an app-level (user) token response instead of a bot-token response, or an unexpected API response shape from an app type change.

Common situations: Slack app configured without a bot user / bot token scope so no bot_user_id is returned; installing an app that was recently converted between user and workspace app types; Slack API behavior changes caught by the defensive check.

Related errors

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