{"record":{"id":"06f677aeb2512787","repo":"mastra-ai/mastra","slug":"knowledge-node-already-exists-in-scope-name","errorCode":null,"errorMessage":"Knowledge node already exists in scope: ${name}","messagePattern":"Knowledge node already exists in scope: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/knowledge/inmemory.ts","lineNumber":215,"sourceCode":"  }\n\n  async updateNode(input: UpdateKnowledgeNodeInput): Promise<KnowledgeNode> {\n    return this.#runAtomicMutation(() => this.#updateNode(input));\n  }\n\n  #updateNode(input: UpdateKnowledgeNodeInput): KnowledgeNode {\n    assertKnowledgeDescriptionWithinBound(input.description);\n    const existing = this.#db.knowledgeNodes.get(input.id);\n    if (!existing) throw new KnowledgeNotFoundError('node', input.id);\n    if (existing.version !== input.version) throw new KnowledgeConflictError(input.id);\n    if (existing.mergedInto) throw new Error(`Cannot update merged knowledge node: ${input.id}`);\n\n    const scope = canonicalizeKnowledgeScope(input.scope ?? existing.scope);\n    const name = (input.name ?? existing.name).trim();\n    const oldKey = recordKey(existing.name, existing.scope);\n    const newKey = recordKey(name, scope);\n    const collision = this.#db.knowledgeNodeKeys.get(newKey);\n    if (collision && collision !== input.id) throw new Error(`Knowledge node already exists in scope: ${name}`);\n\n    const updated: KnowledgeNode = {\n      ...existing,\n      name,\n      kind: input.kind ?? existing.kind,\n      content: input.content ?? existing.content,\n      description: input.description ?? existing.description,\n      scope,\n      version: existing.version + 1,\n      updatedAt: new Date(),\n    };\n    if (oldKey !== newKey) {\n      this.#db.knowledgeNodeKeys.delete(oldKey);\n      this.#db.knowledgeNodeKeys.set(newKey, input.id);\n    }\n    this.#db.knowledgeNodes.set(input.id, updated);\n    if (input.content !== undefined || input.name !== undefined || input.scope !== undefined) {\n      this.#replaceMentions('node', input.id, updated.content ?? '', input.resolutionScope ?? scope, scope);","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/knowledge/inmemory.ts#L197-L233","documentation":"updateNode tried to rename and/or re-scope a node such that the resulting (name, scope) key collides with a different existing node (collision id differs from the node being updated). Names must be unique per scope, so the store rejects the rename.","triggerScenarios":"Calling updateNode with input.name and/or input.scope whose recordKey(name, scope) is already mapped in knowledgeNodeKeys to another node id (collision !== input.id).","commonSituations":"Renaming a node to a name already used by a sibling in the same scope; moving a node into a scope where that name exists; bulk renames racing with node creation.","solutions":["Pick a different name, or a different target scope where the name is free","Check for a name collision first (list/find nodes by name in the target scope) and merge instead of renaming if a duplicate exists","Delete or rename the colliding node first if it is truly obsolete"],"exampleFix":"// before\nawait store.updateNode({ id, version, name: 'existing-name', scope });\n// after\nconst dup = await store.findNodesByName?.('existing-name');\nif (dup?.length) await store.mergeNodes({ sourceId: id, targetId: dup[0].id, sourceVersion: version });\nelse await store.updateNode({ id, version, name: 'existing-name', scope });","handlingStrategy":"validation","validationCode":"const collision = db.knowledgeNodeKeys.get(recordKey(newName, newScope));\nif (collision && collision !== id) throw new Error(`name '${newName}' already used in scope`);","typeGuard":"function isNameFree(nameKey: string, selfId: string, keys: Map<string, string>): boolean {\n  const hit = keys.get(nameKey);\n  return hit === undefined || hit === selfId;\n}","tryCatchPattern":"try {\n  await store.updateNode({ id, version, name: newName, scope });\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Knowledge node already exists in scope')) {\n    await mergeOrCreateWithSuffix(id, newName, scope);\n  } else throw e;\n}","preventionTips":["Check name availability in the target scope before renaming","Prefer merging duplicates over renaming onto an existing name","Generate unique names programmatically (suffixes) in automated flows","Enforce name conventions/registry to reduce accidental collisions"],"tags":["knowledge-store","name-collision","unique-constraint","rename"],"backgroundTag":"duplicate-name-in-scope","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}