{"record":{"id":"451d57b1799a5a47","repo":"mastra-ai/mastra","slug":"knowledgerecord-when-must-be-a-valid-date","errorCode":null,"errorMessage":"KnowledgeRecord when must be a valid date.","messagePattern":"KnowledgeRecord when must be a valid date\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/subconscious/knowledge-write-tools.ts","lineNumber":75,"sourceCode":"        type: 'object',\n        properties: {\n          node: { type: 'string', minLength: 1 },\n          text: { type: 'string', minLength: 1 },\n          scope: scopeLevelSchema,\n          when: { type: 'string' },\n        },\n        required: ['node', 'text'],\n        additionalProperties: false,\n      } satisfies JSONSchema7,\n      execute: async input => {\n        const value = input as { node: string; text: string; scope?: KnowledgeScopeLevel; when?: string };\n        const store = await getStore(memory);\n        const parent = await store.getNode(value.node);\n        if (!parent || parent.mergedInto) throw new Error(`Knowledge node not found: ${value.node}`);\n        requireVisible(parent.scope, options, 'Knowledge node');\n        const scope = resolveWriteScope(options, value.scope);\n        const when = value.when ? new Date(value.when) : undefined;\n        if (when && Number.isNaN(when.getTime())) throw new Error('KnowledgeRecord when must be a valid date.');\n        return store.appendKnowledge({\n          node: parent.id,\n          text: value.text,\n          scope,\n          sourceThreadId: options.sourceThreadId,\n          when,\n          maxScope: options.maxScope,\n          resolutionScope: options.scope,\n          defaultScope: expandKnowledgeScope(options.scope, options.defaultScope),\n        });\n      },\n    }),\n    knowledge_remove: createTool({\n      id: 'knowledge_remove',\n      description: 'Soft-delete a visible record. Curators cannot restore or physically erase knowledge records.',\n      inputSchema: {\n        type: 'object',\n        properties: { recordId: { type: 'string', minLength: 1 } },","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/knowledge-write-tools.ts#L57-L93","documentation":"knowledge_append accepts an optional `when` string that is converted with new Date(value.when) to stamp the record's event time. If the string is present but not parseable (NaN getTime), the handler throws this error instead of persisting a bogus timestamp. The JSON schema only enforces type string, so this runtime check is authoritative.","triggerScenarios":"LLM passes a non-ISO string such as 'last Tuesday', '2024-13-45', 'yesterday', or a locale-formatted date in the knowledge_append `when` field.","commonSituations":"Models emitting natural-language dates; users' free-text dates relayed into tool args; timezone-formatted strings not accepted by the JS Date parser in the runtime environment.","solutions":["Supply `when` as an ISO 8601 string (e.g. '2026-08-29T12:00:00.000Z') or omit it entirely to use the capture time.","Normalize dates to ISO format in the agent pipeline before invoking the tool.","Strengthen the tool description or prompt to state the required ISO 8601 format.","In programmatic callers, validate with !Number.isNaN(new Date(when).getTime()) before execute()."],"exampleFix":"// before\nawait tools.knowledge_append.execute({ node: id, text: 'x', when: 'last Friday' }, ctx);\n// after\nawait tools.knowledge_append.execute({ node: id, text: 'x', when: '2026-08-28T17:30:00.000Z' }, ctx);","handlingStrategy":"validation","validationCode":"function toIsoOrUndefined(when?: string): string | undefined {\n  if (when === undefined) return undefined;\n  const d = new Date(when);\n  if (Number.isNaN(d.getTime())) throw new Error(`Invalid when: ${when}`);\n  return d.toISOString();\n}\nconst safeWhen = toIsoOrUndefined(args.when);","typeGuard":"function isParseableDate(s: unknown): s is string {\n  return typeof s === 'string' && !Number.isNaN(new Date(s).getTime());\n}","tryCatchPattern":"try {\n  return await curatorTools.knowledge_append.execute(args, {} as any);\n} catch (e) {\n  if (e instanceof Error && e.message === 'KnowledgeRecord when must be a valid date.') {\n    return curatorTools.knowledge_append.execute({ ...args, when: undefined }, {} as any); // fall back to capture time\n  }\n  throw e;\n}","preventionTips":["Always emit `when` as ISO 8601 (Date.toISOString()).","Normalize natural-language dates upstream before tool invocation.","Omit `when` when the event time equals capture time.","Mention ISO 8601 explicitly in the tool description/prompt."],"tags":["date-parsing","input-validation","knowledge-append","iso-8601"],"backgroundTag":"invalid-date-format","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}