{"record":{"id":"3bfc0a9d1895ca6b","repo":"mastra-ai/mastra","slug":"pin-not-found-recordid","errorCode":null,"errorMessage":"Pin not found: ${recordId}","messagePattern":"Pin not found: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/subconscious/pinned.ts","lineNumber":177,"sourceCode":"    metadata,\n    resolutionScope: options.scope,\n    defaultScope: expandKnowledgeScope(options.scope, options.defaultScope),\n  });\n}\n\nasync function getStore(memory: PinnedMemory): Promise<KnowledgeStorage> {\n  const store = await memory.storage.getStore('knowledge');\n  if (!store) throw new Error('Pinned knowledge requires a configured knowledge storage domain.');\n  return store;\n}\n\nasync function requirePin(\n  store: KnowledgeStorage,\n  recordId: string,\n  options: PinnedToolsOptions,\n): Promise<KnowledgeRecord> {\n  const record = await store.getKnowledge({ id: recordId, includeDeleted: false });\n  if (!record) throw new Error(`Pin not found: ${recordId}`);\n  const nodeId = await resolvePinnedNodeId(store, options.scope);\n  if (!nodeId || record.node !== nodeId) throw new Error(`Record is not a pin: ${recordId}`);\n  if (!isKnowledgeScopeVisible(record.scope, options.scope)) throw new Error('Pin is outside the visible scope.');\n  return record;\n}\n\n/**\n * Pin lifecycle tools. Pin appends a record on the reserved node; unpin soft-deletes it\n * (auditable, restorable); edit is remove plus append because knowledge records are immutable,\n * so an edited pin carries a new record id.\n */\nexport function createPinnedTools(\n  memory: PinnedMemory,\n  options: PinnedToolsOptions,\n): Record<string, ToolAction<any, any, any>> {\n  return {\n    knowledge_pin: createTool({\n      id: 'knowledge_pin',","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/pinned.ts#L159-L195","documentation":"requirePin loads a knowledge record by id (excluding soft-deleted records) and throws when no record with that id exists. It is the existence half of pin validation — a subsequent check then verifies the record actually belongs to the reserved pinned node. The error surfaces when tools receive an id that never existed or that has been unpinned (soft-deleted).","triggerScenarios":"Calling a pinned tool (e.g. unpin/replace) with a recordId that was soft-deleted (unpinned earlier), was never created, or contains a typo/hallucinated id from the model.","commonSituations":"LLM agent inventing ids to unpin; double-unpinning the same record; ids from a different scope/resource that are not present in this store view; stale UI/client cache after an unpin.","solutions":["List the current pins first and use a returned record id, don't guess","Re-check whether the record was already unpinned (soft-deleted records are not returned)","Verify the recordId string for typos or truncation","If ids come from the model, validate them against the pin list before invoking the tool"],"exampleFix":"// before: unpinning with a stale id\nawait unpinTool.execute({ recordId: 'kn_123' }); // already unpinned\n// Error: Pin not found: kn_123\n// after: resolve a live pin id first\nconst pins = await listPins(memory);\nawait unpinTool.execute({ recordId: pins[0].id });","handlingStrategy":"try-catch","validationCode":"const store = await memory.storage.getStore('knowledge');\nconst record = store ? await store.getKnowledge({ id: recordId, includeDeleted: false }) : undefined;\nif (!record) throw new Error(`Refusing to operate on missing/soft-deleted record: ${recordId}`);","typeGuard":"function isLivePin(record) {\n  return !!record && record.deletedAt == null;\n}","tryCatchPattern":"try {\n  await unpinTool.execute({ recordId });\n} catch (err) {\n  if (err.message.startsWith('Pin not found')) {\n    // already unpinned or bad id: refresh the pin list instead of retrying blindly\n  } else throw err;\n}","preventionTips":["Always source record ids from the pin listing, never from model output alone","Treat 'Pin not found' as likely already-unpinned (soft-deleted ids are excluded)","Avoid caching pin ids across sessions","Trim/validate id strings before calls"],"tags":["not-found","knowledge-store","observational-memory"],"backgroundTag":"record-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}