mastra-ai/mastra · error

Unhandled content part type: ${(exhaustiveCheck as { type: s

Error message

Unhandled content part type: ${(exhaustiveCheck as { type: string }).type}

What it means

This error is thrown by coreUserMessageToParts while converting an AI SDK CoreUserMessage into a MastraDBMessage. The switch over message part types has a `default` branch with a compile-time exhaustive `never` check, so reaching it at runtime means a content part whose `type` was added in a newer AI SDK version (or is otherwise unknown) was passed in. The library throws rather than silently dropping data.

Source

Thrown at client-sdks/react/src/lib/mastra-db/fromCoreUserMessage.ts:42

          case 'image': {
            const mimeType = part.mimeType ?? 'image/*';
            return {
              type: 'file' as const,
              mimeType,
              data: encodeFilePartDataForStorage(part.image, mimeType),
            };
          }
          case 'file': {
            return {
              type: 'file' as const,
              mimeType: part.mimeType,
              data: encodeFilePartDataForStorage(part.data, part.mimeType),
              ...(part.filename !== undefined ? { filename: part.filename } : {}),
            };
          }
          default: {
            const exhaustiveCheck: never = part;
            throw new Error(`Unhandled content part type: ${(exhaustiveCheck as { type: string }).type}`);
          }
        }
      });

const newUserMessage = (parts: MastraMessagePart[]): MastraDBMessage => ({
  id: `user-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`,
  role: 'user',
  createdAt: new Date(),
  content: {
    format: 2,
    parts,
  },
});

export const fromCoreUserMessageToMastraDBMessage = (coreUserMessage: CoreUserMessage): MastraDBMessage =>
  newUserMessage(coreUserMessageToParts(coreUserMessage));

/**

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade @mastra/client-js / @mastra/core (and the react SDK) to a version whose converter covers your AI SDK's part types
2. Align the `ai` package version with the version the Mastra packages were built against
3. Intercept and strip/convert unknown parts from the message before calling the converter
4. Extend/wrap the converter to handle the new part type, or file an issue so the part type gets a case

Example fix

// before
const parts = message.content; // contains { type: 'reasoning', ... } unknown to converter
fromCoreUserMessageToMastraDBMessage(message); // throws
// after
const supported = message.content.filter(p => ['text','image','file'].includes(p.type));
fromCoreUserMessageToMastraDBMessage({ ...message, content: supported });

const KNOWN_PART_TYPES = ['text','image','file'];
if (!message.content.every(p => KNOWN_PART_TYPES.includes(p.type))) {
  throw new Error('Message contains part types unsupported by this Mastra SDK version');
}

function isSupportedPart(part: { type: string }): part is TextPart | ImagePart | FilePart {
  return ['text','image','file'].includes(part.type);
}

try {
  const dbMessage = fromCoreUserMessageToMastraDBMessage(message);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unhandled content part type')) {
    console.warn('Skipping unsupported part types; upgrade SDK to support them');
    // fallback: filter unknown parts and retry
  } else throw err;
}

When it happens

Trigger: Calling fromCoreUserMessageToMastraDBMessage (via coreUserMessageToParts) with a user message containing a part type not covered by the switch — e.g. a newly introduced AI SDK part kind like a novel file/tool/audio variant that the converter has no case for.

Common situations: Mixing AI SDK major versions (message produced by a newer ai package, converted by an older @mastra/client-js/react); manually constructing CoreUserMessage parts with an unexpected `type` string; forwarding model/provider-specific parts straight through.

Related errors

• runId is required when resumeData is provided
• Agent ${agentId} not found
• Messages must be an array of UIMessage objects
• Path must include :agentId to route to the correct agent or
• Agent ID is required

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