mastra-ai/mastra · error · HTTPException

Channel "${platform}" is not registered. Available: ${availa

Error message

Channel "${platform}" is not registered. Available: ${available || 'none'}

What it means

getChannelOrThrow looks up a ChannelProvider by ID in mastra.channels and throws a 404 HTTPException when no registered channel matches the requested platform. The message lists all registered channel IDs (or 'none') so callers can see what is available. The instance itself supports channels (the feature gate passed) but this particular platform is not registered.

Source

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

import { assertWriteAccess, getCallerAuthorId, hasAdminBypass, hasScopedPermission } from './authorship';
import { handleError } from './error';

// ============================================================================
// Feature gate + helpers
// ============================================================================

function assertChannelsAvailable(): void {
  if (!coreFeatures.has('channels')) {
    throw new HTTPException(501, { message: 'Channels require a newer version of @mastra/core' });
  }
}

function getChannelOrThrow(mastra: Mastra, platform: string): ChannelProvider {
  const channels = Object.values(mastra.channels ?? {});
  const channel = channels.find(c => c.id === platform);
  if (!channel) {
    const available = channels.map(c => c.id).join(', ');
    throw new HTTPException(404, {
      message: `Channel "${platform}" is not registered. Available: ${available || 'none'}`,
    });
  }
  return channel;
}

/**
 * Unified connect/disconnect authorization.
 *
 * - Stored agent exists → same write access as editing the agent record.
 * - Code-defined agent (no stored record) → route's `requiresAuth` is the gate.
 * - Agent doesn't exist anywhere:
 *   - connect → 404 (can't connect a channel to a non-existent agent)
 *   - disconnect → orphan cleanup, gated on `channels:write`
 */
async function assertChannelAgentWriteAccess(
  mastra: Mastra,
  requestContext: RequestContext,

View on GitHub (pinned to 75dd419e61)

Solutions

Use one of the IDs listed in the error's 'Available:' list instead of the requested platform.
Register the channel provider on the Mastra instance (add it to the channels config in new Mastra({...})).
Check exact ID casing — the lookup is a strict equality match on channel.id.
Confirm you are querying the same deployment where the channel is registered.

Example fix

// before
new Mastra({ agents, /* channels missing */ });

// after
import { SlackChannel } from './channels/slack';
new Mastra({ agents, channels: { slack: new SlackChannel({ token: process.env.SLACK_TOKEN }) } });

Defensive patterns

Strategy: validation

Validate before calling

const platforms = await listChannelPlatforms();
if (!platforms.includes(platform)) {
  throw new Error(`Channel "${platform}" not registered. Available: ${platforms.join(', ')}`);
}

Type guard

function isRegisteredChannel(channels: { id: string }[], platform: string): boolean {
  return channels.some(c => c.id === platform);
}

Try / catch

try {
  await connectChannel(platform, agentId);
} catch (e) {
  if (e.status === 404 && e.message.includes('is not registered')) {
    // parse 'Available:' from message or re-list platforms and prompt user
  } else throw e;
}

Prevention

Populate channel pickers from the platforms list endpoint, not free text.
Register every channel provider you reference in the Mastra constructor.
Match channel IDs exactly (case-sensitive).
Verify channel registration with a startup log/health check per environment.

When it happens

Trigger: Calling channel routes (e.g. connect/disconnect, platform-scoped listings) with a platform path parameter that is not an ID in mastra.channels on the current instance.

Common situations: Typo in the platform slug (e.g. 'slack' vs 'Slack' vs 'whatsapp'); channel plugin not added to the Mastra constructor; channel registered on a different environment/instance than the one being queried; channel registration failed silently at startup.

Related errors

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