{"record":{"id":"56450544e2189a5b","repo":"mastra-ai/mastra","slug":"updating-node-content-requires-expectedversion","errorCode":null,"errorMessage":"Updating node content requires expectedVersion.","messagePattern":"Updating node content requires expectedVersion\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/subconscious/knowledge-write-tools.ts","lineNumber":263,"sourceCode":"          throw new Error(`capture-guidance is limited to ${MAX_GUIDANCE_LENGTH} characters.`);\n        }\n        const store = await getStore(memory);\n        const scope = resolveWriteScope(options, value.scope);\n        const resolvedNode = await store.resolveNode({ name, scope });\n        const existing =\n          resolvedNode && knowledgeScopeKey(resolvedNode.scope) === knowledgeScopeKey(scope) ? resolvedNode : null;\n        if (!existing) {\n          if (value.expectedVersion !== undefined)\n            throw new Error('expectedVersion is only valid for an existing node.');\n          return store.createNode({\n            name,\n            kind: value.kind ?? 'document',\n            content: value.content,\n            scope,\n            resolutionScope: options.scope,\n          });\n        }\n        if (value.expectedVersion === undefined) throw new Error('Updating node content requires expectedVersion.');\n        return store.updateNode({\n          id: existing.id,\n          version: value.expectedVersion,\n          kind: value.kind,\n          content: value.content,\n          resolutionScope: options.scope,\n        });\n      },\n    }),\n  };\n}\n","sourceCodeStart":245,"sourceCodeEnd":275,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/knowledge-write-tools.ts#L245-L275","documentation":"When the node upsert targets an existing node, the tool requires expectedVersion to perform the content update, since updateNode relies on version-based optimistic concurrency to prevent lost updates. Omitting it on an existing node throws this error before touching storage.","triggerScenarios":"Calling the upsert tool with a name that resolves to an existing node in the same scope but without expectedVersion in the input.","commonSituations":"Reusable code paths that always omit expectedVersion; a node created between your check and your write so your create path flips into an update path; hand-written tool calls from the LLM missing the field.","solutions":["Fetch the current node via store.resolveNode({ name, scope }) and pass its version as expectedVersion","Use knowledge_update_node-style flows that always carry expectedVersion for existing nodes","In code, branch: resolve first; create without version if absent, update with version if present"],"exampleFix":"// before\nawait tool.execute({ name, content });\n// after\nconst existing = await store.resolveNode({ name, scope });\nawait tool.execute({ name, content, expectedVersion: existing?.version });","handlingStrategy":"validation","validationCode":"const existing = await store.resolveNode({ name, scope });\nconst input = existing\n  ? { name, content, expectedVersion: existing.version }\n  : { name, content };","typeGuard":null,"tryCatchPattern":"try {\n  await tool.execute(input);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('requires expectedVersion')) {\n    const node = await store.resolveNode({ name, scope });\n    await tool.execute({ ...input, expectedVersion: node.version });\n  } else throw e;\n}","preventionTips":["Always resolve before upsert so update paths carry expectedVersion","Treat version as required for any write to an existing node","Retry on version conflicts by refetching the node"],"tags":["validation","memory","optimistic-concurrency"],"backgroundTag":"optimistic-lock-version-missing","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}