{"record":{"id":"10fa281aa31a5f55","repo":"mastra-ai/mastra","slug":"channels-require-a-newer-version-of-mastra-core","errorCode":null,"errorMessage":"Channels require a newer version of @mastra/core","messagePattern":"Channels require a newer version of @mastra/core","errorType":"http","errorClass":"HTTPException","httpStatus":501,"severity":"error","filePath":"packages/server/src/server/handlers/channels.ts","lineNumber":28,"sourceCode":"  channelAgentPathParams,\n  connectChannelBodySchema,\n  listChannelPlatformsResponseSchema,\n  listChannelInstallationsResponseSchema,\n  connectChannelResponseSchema,\n  disconnectChannelResponseSchema,\n} from '../schemas/channels';\nimport { createRoute } from '../server-adapter/routes/route-builder';\n\nimport { assertWriteAccess, getCallerAuthorId, hasAdminBypass, hasScopedPermission } from './authorship';\nimport { handleError } from './error';\n\n// ============================================================================\n// Feature gate + helpers\n// ============================================================================\n\nfunction assertChannelsAvailable(): void {\n  if (!coreFeatures.has('channels')) {\n    throw new HTTPException(501, { message: 'Channels require a newer version of @mastra/core' });\n  }\n}\n\nfunction getChannelOrThrow(mastra: Mastra, platform: string): ChannelProvider {\n  const channels = Object.values(mastra.channels ?? {});\n  const channel = channels.find(c => c.id === platform);\n  if (!channel) {\n    const available = channels.map(c => c.id).join(', ');\n    throw new HTTPException(404, {\n      message: `Channel \"${platform}\" is not registered. Available: ${available || 'none'}`,\n    });\n  }\n  return channel;\n}\n\n/**\n * Unified connect/disconnect authorization.\n *","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/channels.ts#L10-L46","documentation":"assertChannelsAvailable is a feature gate: it throws a 501 HTTPException when the installed @mastra/core does not expose the 'channels' feature (coreFeatures.has('channels') is false). All channel routes (list platforms, list installations, connect, disconnect) are gated by it. 501 signals that this server version cannot serve channels because its core dependency predates the feature.","triggerScenarios":"Calling any /api/channels* route (list platforms, list installations, connect, disconnect) on a server built against an @mastra/core version without the channels feature export.","commonSituations":"Partial upgrade — @mastra/server updated but @mastra/core left old; monorepo dependency drift where the resolved core is stale; a custom build where the channels feature flag is absent.","solutions":["Upgrade @mastra/core to a version that includes the channels feature (matching the @mastra/server version's requirement).","Run your package manager install to reconcile workspace/lockfile versions of @mastra/core and @mastra/server.","Verify coreFeatures picks up 'channels' at runtime (check the resolved core version actually installed, not the one in your manifest).","Rebuild/redeploy the server after the upgrade so the feature detection runs against the new core."],"exampleFix":"// before\n\"dependencies\": { \"@mastra/core\": \"^0.10.0\", \"@mastra/server\": \"^0.12.0\" }\n\n// after\n\"dependencies\": { \"@mastra/core\": \"^0.12.0\", \"@mastra/server\": \"^0.12.0\" } // core supports channels\n// then: pnpm install && rebuild server","handlingStrategy":"fallback","validationCode":"import { coreFeatures } from '@mastra/core'; // or check installed core version\nif (!coreFeatures.has('channels')) {\n  console.warn('channels unsupported by installed @mastra/core — hiding channel UI');\n}","typeGuard":"function channelsSupported(coreVersion: string): boolean {\n  return semver.gte(coerce(coreVersion) ?? '0.0.0', MIN_CORE_VERSION_WITH_CHANNELS);\n}","tryCatchPattern":"try {\n  await listChannelPlatforms();\n} catch (e) {\n  if (e.status === 501 && e.message.includes('newer version of @mastra/core')) {\n    // degrade gracefully: hide channels feature, prompt upgrade\n  } else throw e;\n}","preventionTips":["Keep @mastra/core and @mastra/server versions in lockstep.","Run a dependency-consistency check in CI for @mastra packages.","Feature-detect channels at app startup and hide dependent UI when absent.","After upgrading core, rebuild and redeploy so feature flags re-evaluate."],"tags":["http-501","channels","feature-gate","version-mismatch"],"backgroundTag":"feature-not-supported-version","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}