{"record":{"id":"b99c66033d0f01cf","repo":"mastra-ai/mastra","slug":"dataset-item-payload-not-serializable","errorCode":"DATASET_ITEM_PAYLOAD_NOT_SERIALIZABLE","errorMessage":"Dataset item payload must be JSON-serializable: ${issue.reason}.","messagePattern":"Dataset item payload must be JSON-serializable: (.+?)\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/datasets/serialization.ts","lineNumber":86,"sourceCode":"\n  return undefined;\n}\n\ntype SerializableDatasetItemPayload = Partial<Omit<DatasetItemPayload, 'scorerIds'>> &\n  Pick<UpdateDatasetItemInput, 'scorerIds'>;\n\nexport function validateDatasetItemPayloadSerialization(payload: SerializableDatasetItemPayload, path: string): void {\n  const ancestors = new WeakMap<object, string>();\n  ancestors.set(payload, path);\n\n  for (const key of Object.keys(payload)) {\n    const fieldValue = (payload as Record<string, unknown>)[key];\n    // Omitted optional fields: only nested undefined values are lossy.\n    if (fieldValue === undefined) continue;\n\n    const issue = findSerializationIssue(fieldValue, formatPath(path, key), ancestors);\n    if (issue) {\n      throw new MastraError({\n        id: 'DATASET_ITEM_PAYLOAD_NOT_SERIALIZABLE',\n        text: `Dataset item payload must be JSON-serializable: ${issue.reason}.`,\n        domain: 'STORAGE',\n        category: 'USER',\n        details: issue.referencePath\n          ? { path: issue.path, referencePath: issue.referencePath }\n          : { path: issue.path, reason: issue.reason },\n      });\n    }\n  }\n\n  try {\n    JSON.stringify(payload);\n  } catch (error) {\n    throw new MastraError({\n      id: 'DATASET_ITEM_PAYLOAD_NOT_SERIALIZABLE',\n      text: `Dataset item payload at ${path} must be JSON-serializable: ${error instanceof Error ? error.message : String(error)}`,\n      domain: 'STORAGE',","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/datasets/serialization.ts#L68-L104","documentation":"Pre-write validation that a dataset item's payload can round-trip through JSON. When a field contains a non-serializable value (function, BigInt, class instance, circular reference), a MastraError with code DATASET_ITEM_PAYLOAD_NOT_SERIALIZABLE is thrown, carrying the offending path and a reference path for class instances.","triggerScenarios":"updateItem or batchInsertItems with a payload containing a function, Symbol, BigInt, Date-like class instance, Map/Set, or a circular structure; computed object values returning class instances instead of plain objects.","commonSituations":"Passing AI/tool call results containing class instances directly as item payloads; embedding a callback in the payload by accident; building payloads from DB rows that include Buffer/BigInt columns.","solutions":["Convert non-plain values before storing: JSON.parse(JSON.stringify(payload)) or explicit mapping to primitives.","Convert BigInt to string and Date to ISO string explicitly.","Replace class instances with plain objects ({ ...instance }) or a toDTO().","Remove circular references or replace with ids/refs."],"exampleFix":"// before\nawait storage.datasets.updateItem({ datasetId, id, payload: { createdAt: new Date(), meta: bigIntCount } });\n// after\nawait storage.datasets.updateItem({ datasetId, id, payload: { createdAt: new Date().toISOString(), meta: String(bigIntCount) } });","handlingStrategy":"validation","validationCode":"function isJsonSerializable(value: unknown, seen = new WeakSet<object>()): boolean {\n  if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) return true;\n  if (typeof value === 'bigint' || typeof value === 'function' || typeof value === 'symbol') return false;\n  if (typeof value !== 'object') return false;\n  if (seen.has(value)) return false;\n  seen.add(value);\n  return Object.values(value as Record<string, unknown>).every(v => isJsonSerializable(v, seen));\n}\n// before writing: if (!isJsonSerializable(payload)) sanitize(payload);","typeGuard":"function isPlainPayload(p: unknown): p is Record<string, string | number | boolean | null | Array<unknown> | object> {\n  return isJsonSerializable(p);\n}","tryCatchPattern":"try {\n  await storage.datasets.updateItem({ datasetId, id, payload });\n} catch (e) {\n  if ((e as any).id === 'DATASET_ITEM_PAYLOAD_NOT_SERIALIZABLE') {\n    const { path, referencePath } = (e as any).details ?? {};\n    // fix payload at `path` (convert class instance at referencePath to plain object)\n  } else throw e;\n}","preventionTips":["Map payloads to plain JSON types (string/number/boolean/null/array/plain object) at construction.","Convert Date -> ISO string and BigInt -> string explicitly.","Strip functions and class instances before persisting.","Reuse one sanitize-payload helper in all write paths."],"tags":["storage","datasets","serialization","json","user-error"],"backgroundTag":"json-serialization-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}