{"record":{"id":"edf768d88f999dbf","repo":"mastra-ai/mastra","slug":"invalid-system-message-format-edf768","errorCode":"INVALID_SYSTEM_MESSAGE_FORMAT","errorMessage":"Invalid system message format. System messages must be CoreMessage format with 'role' and 'content' properties. The content should be a string or valid content array.","messagePattern":"Invalid system message format\\. System messages must be CoreMessage format with 'role' and 'content' properties\\. The content should be a string or valid content array\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/message-list/message-list.ts","lineNumber":1679,"sourceCode":"    }\n\n    if (message.role === `system`) {\n      // In the past system messages were accidentally stored in the db. these should be ignored because memory is not supposed to store system messages.\n      if (messageSource === `memory`) return null;\n\n      // Check if the message is in a supported format for system messages\n      const isSupportedSystemFormat =\n        TypeDetector.isAIV4CoreMessage(message) ||\n        TypeDetector.isAIV6CoreMessage(message) ||\n        TypeDetector.isAIV5CoreMessage(message) ||\n        TypeDetector.isMastraDBMessage(message);\n\n      if (isSupportedSystemFormat) {\n        return this.addSystem(message);\n      }\n\n      // if we didn't add the message and we didn't ignore this intentionally, then it's a problem!\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 be CoreMessage format with 'role' and 'content' properties. The content should be a string or valid content array.`,\n        details: {\n          messageSource,\n          receivedMessage: JSON.stringify(message, null, 2),\n        },\n      });\n    }\n\n    const messageV2 = convertInputToMastraDBMessage(message, messageSource, this.createAdapterContext());\n    const signalMetadata =\n      messageV2.role === 'signal'\n        ? (messageV2.content.metadata?.signal as { acceptedAt?: string; createdAt?: string } | undefined)\n        : undefined;\n    if (messageSource === 'input' && messageV2.role === 'signal' && !signalMetadata?.acceptedAt) {\n      const acceptedAt = signalMetadata?.createdAt ?? messageV2.createdAt.toISOString();","sourceCodeStart":1661,"sourceCodeEnd":1697,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/message-list/message-list.ts#L1661-L1697","documentation":"MessageList.add() validates every system-role message against known message shapes (AI SDK v4/v5/v6 CoreMessage, or MastraDBMessage). If the message has role 'system' but none of the type detectors recognize its shape, the list refuses to store it and throws INVALID_SYSTEM_MESSAGE_FORMAT. This guards the internal prompt pipeline, which assumes system messages conform to the CoreMessage contract ('role' plus string or content-array 'content').","triggerScenarios":"Calling messageList.add({ role: 'system', ... }) or agent methods that ingest memory/input messages with a system message whose shape fails TypeDetector.isAIV4CoreMessage / isAIV5CoreMessage / isAIV6CoreMessage / isMastraDBMessage — e.g. content is an object, undefined, or an unexpected array element shape, or the message uses a custom/legacy message class.","commonSituations":"Hand-rolled message objects from custom storage layers or ORMs that serialize content differently; mixing Mastra Memory output with older AI SDK message versions; loading messages persisted by an older Mastra version into a new MessageList; typos like 'roles' instead of 'role'.","solutions":["Ensure the system message is a plain CoreMessage: { role: 'system', content: 'your instructions' } with content as a string or a valid content-part array.","Check the receivedMessage in error details to see what shape actually arrived and fix the producer that serialized it.","If migrating from an older Mastra/AI SDK version, convert stored messages to the current CoreMessage/DBMessage format before adding them.","If passing pre-built message arrays to an agent, use the types from @mastra/core (CoreMessage / MastraDBMessage) instead of ad-hoc objects."],"exampleFix":"// before\nmessages.push({ role: 'system', content: { text: 'You are helpful' } } as any);\n// after\nmessages.push({ role: 'system', content: 'You are helpful' });","handlingStrategy":"type-guard","validationCode":"function isValidSystemMessage(m: unknown): boolean {\n  return (\n    !!m && typeof m === 'object' && (m as any).role === 'system' &&\n    (typeof (m as any).content === 'string' ||\n      (Array.isArray((m as any).content) && (m as any).content.length > 0))\n  );\n}\nif (!isValidSystemMessage(msg)) throw new Error('bad system message');","typeGuard":"function isCoreSystemMessage(m: unknown): m is { role: 'system'; content: string | Array<{ type: string; [k: string]: unknown }> } {\n  return typeof m === 'object' && m !== null &&\n    (m as any).role === 'system' &&\n    (typeof (m as any).content === 'string' ||\n      (Array.isArray((m as any).content) && (m as any).content.every((p: unknown) => typeof p === 'object' && p !== null)));\n}","tryCatchPattern":"try {\n  messageList.add(msg, 'memory');\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'INVALID_SYSTEM_MESSAGE_FORMAT') {\n    console.error('System message rejected:', e.detail?.receivedMessage);\n    return; // skip or re-serialize to CoreMessage\n  }\n  throw e;\n}","preventionTips":["Construct system messages only via typed helpers (CoreMessage types from the AI SDK).","Never hand-serialize system messages through custom storage without re-validating on read.","Add a unit test asserting persisted messages round-trip through MessageList.add."],"tags":["message-list","system-message","validation","agent"],"backgroundTag":"invalid-system-message-format","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}