{"record":{"id":"4a72cc3d9061a9aa","repo":"mastra-ai/mastra","slug":"invalid-system-message-format","errorCode":"INVALID_SYSTEM_MESSAGE_FORMAT","errorMessage":"Invalid system message format. System messages must include 'role' and 'content' properties. The content should be a string.","messagePattern":"Invalid system message format\\. System messages must include 'role' and 'content' properties\\. The content should be a string\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/message-list/adapters/AIV4Adapter.ts","lineNumber":377,"sourceCode":"      role: m.role === 'signal' ? (isUserMessageSignal ? 'user' : 'system') : m.role,\n      content: m.role === 'signal' && !isUserMessageSignal ? '' : m.content.content || contentString,\n      createdAt: m.createdAt,\n      parts: v4Parts,\n      experimental_attachments: experimentalAttachments,\n    };\n    // Preserve metadata if present\n    if (m.content.metadata) {\n      uiMessage.metadata = m.content.metadata;\n    }\n    return uiMessage;\n  }\n\n  /**\n   * Converts a MastraDBMessage system message directly to AIV4 CoreMessage format\n   */\n  static systemToV4Core(message: MastraDBMessage): CoreMessageV4 {\n    if (message.role !== `system` || !message.content.content)\n      throw new MastraError({\n        id: 'INVALID_SYSTEM_MESSAGE_FORMAT',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text: `Invalid system message format. System messages must include 'role' and 'content' properties. The content should be a string.`,\n        details: {\n          receivedMessage: JSON.stringify(message, null, 2),\n        },\n      });\n\n    const coreMessage: CoreMessageV4 = { role: 'system', content: message.content.content };\n\n    // Preserve message-level providerMetadata as experimental_providerMetadata (V4 field name)\n    if (message.content.providerMetadata) {\n      coreMessage.experimental_providerMetadata = message.content.providerMetadata;\n    }\n\n    return coreMessage;\n  }","sourceCodeStart":359,"sourceCodeEnd":395,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/message-list/adapters/AIV4Adapter.ts#L359-L395","documentation":"MastraError thrown by MessageList's systemToV4Core when converting a stored system message into AI SDK v4 CoreMessage format. A system message must have role === 'system' and a non-empty content.content string; otherwise the adapter cannot produce a valid CoreMessage. It is categorized USER because the malformed message came from caller input, not the library.","triggerScenarios":"Passing a message to MessageList/agent memory where message.role !== 'system' (e.g. 'System', 'assistant') but positioned as a system message, or a system message whose content.content is undefined/null/empty (e.g. { role: 'system', content: 'instructions' } string form instead of the structured content object, or content stripped during serialization).","commonSituations":"Constructing MastraDBMessage by hand with a plain-string content field; loading persisted messages from custom storage where content was stored as a string; mixing AI SDK message shapes with Mastra DB messages; typos like role: 'System'.","solutions":["Ensure the message is { role: 'system', content: { content: '...' } } with a non-empty string in content.content before adding it to MessageList.","If starting from a plain string, wrap it: { role: 'system', content: { content: mySystemPrompt }, createdAt: new Date() }.","Check persisted/storage records for system messages whose content was flattened or truncated and repair them.","Inspect details.receivedMessage in the error to see the exact offending message."],"exampleFix":"// before\nconst msg = { role: 'system', content: 'You are helpful.' };\nmessageList.add(msg);\n\n// after\nconst msg = { role: 'system', content: { content: 'You are helpful.' } };\nmessageList.add(msg);","handlingStrategy":"validation","validationCode":"function assertValidSystemMessage(msg: { role: string; content: unknown }): void {\n  if (msg.role !== 'system' || typeof (msg.content as any)?.content !== 'string' || !(msg.content as any).content) {\n    throw new Error(`Invalid system message: ${JSON.stringify(msg).slice(0, 200)}`);\n  }\n}","typeGuard":"function isSystemDBMessage(m: any): m is { role: 'system'; content: { content: string } } {\n  return !!m && m.role === 'system' && typeof m.content?.content === 'string' && m.content.content.length > 0;\n}","tryCatchPattern":"try {\n  messageList.add(candidate);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'INVALID_SYSTEM_MESSAGE_FORMAT') {\n    logger.error('Bad system message, skipping:', e.details.receivedMessage);\n    return;\n  }\n  throw e;\n}","preventionTips":["Always build system messages via a helper that produces { role: 'system', content: { content: string } }.","Never store/serialize system prompts as plain-string content in MastraDBMessage records.","Validate messages loaded from custom storage before adding to MessageList.","Check details.receivedMessage in the error payload to pinpoint the malformed record."],"tags":["agent","message-conversion","system-message","validation"],"backgroundTag":"invalid-message-format","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}