mastra-ai/mastra · error

Unsupported output format: ${format}

Error message

Unsupported output format: ${format}

What it means

AgentMemory or message conversion code only supports a fixed set of output format strings ('AIV5.UI', 'AIV5.Model', 'AIV6.UI', etc.). This error means the `format` passed to the message-dump/convert API did not match any case in the switch. It is a strict enum-guard, so any typo or unsupported format string fails fast instead of silently returning undefined.

Source

Thrown at packages/core/src/agent/message-list/utils/convert-messages.ts:84

   */
  to(format: 'AIV6.UI'): AIV6.UIMessage[];
  to(format: OutputFormat): unknown[] {
    switch (format) {
      // Old format keys (backward compatibility)
      case 'Mastra.V2':
        return this.messageList.get.all.db();
      case 'AIV4.UI':
        return this.messageList.get.all.aiV4.ui();
      case 'AIV4.Core':
        return this.messageList.get.all.aiV4.core();
      case 'AIV5.UI':
        return this.messageList.get.all.aiV5.ui();
      case 'AIV5.Model':
        return this.messageList.get.all.aiV5.model();
      case 'AIV6.UI':
        return this.messageList.get.all.aiV6.ui();
      default:
        throw new Error(`Unsupported output format: ${format}`);
    }
  }
}

/**
 * Convert messages from any supported format to another format.
 *
 * @param messages - Input messages in any supported format. Accepts:
 *   - AI SDK v4 formats: UIMessage, CoreMessage, Message
 *   - AI SDK v5 formats: UIMessage, ModelMessage
 *   - Mastra formats: MastraMessageV1 (input only), MastraDBMessage
 *   - Simple strings (will be converted to user messages)
 *   - Arrays of any of the above
 *
 * @returns A converter object with a `.to()` method to specify the output format
 *
 * @example
 * ```typescript

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use one of the exact supported format literals shown in the switch: 'AIV5.UI', 'AIV5.Model', 'AIV6.UI' (check convert-messages.ts for the full list).
2. Import a format constant/type from the library instead of typing the string by hand, so TypeScript catches invalid values at compile time.
3. If you need a format not in the list, convert the output yourself (e.g. take 'AIV5.UI' and transform to your target shape) rather than passing a custom format string.
4. If on an older Mastra version, upgrade — new format keys may have been added.

Example fix

// before
const messages = memory.dump('v5-ui');
// after
const messages = memory.dump('AIV5.UI');

const SUPPORTED = ['AIV5.UI', 'AIV5.Model', 'AIV6.UI'] as const;
type Format = typeof SUPPORTED[number];
const isFormat = (f: string): f is Format => (SUPPORTED as readonly string[]).includes(f);
if (!isFormat(format)) throw new TypeError(`format must be one of ${SUPPORTED.join(', ')}`);

function isOutputFormat(f: unknown): f is 'AIV5.UI' | 'AIV5.Model' | 'AIV6.UI' {
  return f === 'AIV5.UI' || f === 'AIV5.Model' || f === 'AIV6.UI';
}

try {
  messages = dump(format);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unsupported output format')) {
    messages = dump('AIV5.UI'); // fallback to default format
  } else throw e;
}

When it happens

Trigger: Calling a method that converts MessageList contents (e.g. agent memory dump / message serialization) with a `format` string that is not one of the supported keys handled in convert-messages.ts, such as 'AIV4.UI', 'v5-ui', or a lowercased 'aiv5.ui'.

Common situations: Typos in format constants; copying code from an older version of Mastra that used different format names; dynamically building the format string from config; passing a format supported in a different package/version that core doesn't handle yet.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown target type: ${targetType}
• No data source: provide datasetId or data
• No task: provide targetType+targetId or task
• Invalid model configuration provided
• AcpAgent does not support resuming suspended generate calls

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