mastra-ai/mastra · error · HTTPException

Channel "${platform}" does not support programmatic connecti

Error message

Channel "${platform}" does not support programmatic connection

What it means

The connect-channel handler looks up the channel instance registered on the Mastra instance for the requested platform and throws HTTP 400 when the channel object has no `connect` method. Channels only expose programmatic connect/disconnect when the underlying integration supports it; presence-only channels (e.g. ones that connect via external dashboard configuration) do not implement it.

Source

Thrown at packages/server/src/server/handlers/channels.ts:184

 */
export const CONNECT_CHANNEL_ROUTE = createRoute({
  method: 'POST',
  path: '/channels/:platform/connect',
  responseType: 'json',
  pathParamSchema: channelPlatformPathParams,
  bodySchema: connectChannelBodySchema,
  responseSchema: connectChannelResponseSchema,
  summary: 'Connect agent to channel',
  description: 'Creates a platform app for the agent and returns an OAuth authorization URL',
  tags: ['Channels'],
  requiresAuth: true,
  handler: async ({ mastra, requestContext, platform, agentId, options }) => {
    assertChannelsAvailable();
    try {
      const channel = getChannelOrThrow(mastra, platform);

      if (!channel.connect) {
        throw new HTTPException(400, {
          message: `Channel "${platform}" does not support programmatic connection`,
        });
      }

      await assertChannelAgentWriteAccess(mastra, requestContext, agentId, 'connect');

      return await channel.connect(agentId, options);
    } catch (error) {
      return handleError(error, 'Error connecting agent to channel');
    }
  },
});

/**
 * POST /channels/:platform/:agentId/disconnect - Disconnect an agent from a platform
 */
export const DISCONNECT_CHANNEL_ROUTE = createRoute({
  method: 'POST',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check whether the channel class for that platform implements a connect() method before calling the API; configure it through its native setup flow instead
2. Register a channel implementation that supports programmatic connection (implements connect) for that platform
3. Upgrade @mastra/core / the channel package if a newer version added connect support for your channel
4. Use GET the channel list/capabilities endpoint to confirm which platforms support connect

Example fix

// before
await client.connectChannel({ platform: 'sms', agentId: 'agent-1' }) // sms channel has no connect
// after
const channels = await client.listChannels();
if (channels.find(c => c.platform === 'slack')?.supportsConnect) {
  await client.connectChannel({ platform: 'slack', agentId: 'agent-1' });
}

const channel = channels.find(c => c.platform === platform);
if (!channel?.supportsConnect) throw new Error(`Platform ${platform} does not support programmatic connect`);

function supportsConnect(ch: { connect?: unknown } | undefined): ch is { connect: Function } {
  return !!ch && typeof ch.connect === 'function';
}

try {
  await client.connectChannel({ platform, agentId });
} catch (e) {
  if (e.status === 400 && /does not support programmatic connection/.test(e.message)) {
    // configure this channel through its external setup flow instead
    return { connected: false, reason: 'manual-setup-required' };
  }
  throw e;
}

When it happens

Trigger: POSTing to the channel connect route with a platform whose registered channel class does not implement `connect` (channel.connect is undefined), even though the channel itself exists in mastra.getChannels().

Common situations: Attempting to programmatically connect a channel that is wired up via webhook/manifest configuration (e.g. some Slack or telephony channels registered via external setup); calling connect on a channel type that was swapped for a variant lacking connect; copy-pasting connect calls across channel platforms.

Related errors

• Channel "${platform}" does not support programmatic disconne
• Workflow ID is required
• perPage must be a positive integer
• page must be a non-negative integer
• Run ID is required

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