{"record":{"id":"6d35980bb73b9b7c","repo":"mastra-ai/mastra","slug":"this-name-entity-with-id-id-already-exists","errorCode":null,"errorMessage":"${this.name}: entity with id ${id} already exists","messagePattern":"(.+?): entity with id (.+?) already exists","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/filesystem-versioned.ts","lineNumber":492,"sourceCode":"      }\n    }\n\n    return result;\n  }\n\n  // ==========================================================================\n  // Entity CRUD\n  // ==========================================================================\n\n  async getById(id: string): Promise<TEntity | null> {\n    this.hydrate();\n    return this.entities.has(id) ? structuredClone(this.entities.get(id)!) : null;\n  }\n\n  async createEntity(id: string, entity: TEntity): Promise<TEntity> {\n    this.hydrate();\n    if (this.entities.has(id)) {\n      throw new Error(`${this.name}: entity with id ${id} already exists`);\n    }\n    this.entities.set(id, structuredClone(entity));\n    return structuredClone(entity);\n  }\n\n  async updateEntity(id: string, updates: Record<string, unknown>): Promise<TEntity> {\n    this.hydrate();\n    const existing = this.entities.get(id);\n    if (!existing) {\n      throw new Error(`${this.name}: entity with id ${id} not found`);\n    }\n\n    const updated = { ...existing } as Record<string, unknown>;\n\n    for (const [key, value] of Object.entries(updates)) {\n      if (key === 'id') continue;\n      if (value === undefined) continue;\n","sourceCodeStart":474,"sourceCodeEnd":510,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/filesystem-versioned.ts#L474-L510","documentation":"createEntity on a FilesystemVersioned store refuses to overwrite: it hydrates state from disk, and if an entity with the given id already exists in the in-memory map it throws instead of replacing it. This protects versioned entity data from silent data loss. Use update or upsert semantics instead of create for existing ids.","triggerScenarios":"Calling store.create('entities', entity) (which delegates to createEntity) with an id that already exists in the store; calling createEntity(id, entity) directly twice with the same id; a race where two requests create the same id concurrently after hydrate.","commonSituations":"Seeding scripts re-run without clearing storage; importing fixtures whose ids collide with existing data; retry logic that re-issues a create after a timeout even though the first write succeeded.","solutions":["Check existence first with get() or a getEntity call and switch to the update path when the id already exists.","Generate a fresh unique id (uuid/nanoid) instead of reusing an id derived from user input.","Delete the existing entity first if replacement is truly intended, then recreate."],"exampleFix":"// before\nawait store.create('agents', { id: 'my-agent', ...data });\n// after\nconst existing = await store.get('agents', 'my-agent');\nif (existing) {\n  await store.update('agents', 'my-agent', data);\n} else {\n  await store.create('agents', { id: 'my-agent', ...data });\n}","handlingStrategy":"validation","validationCode":"const existing = await store.get('entities', id);\nif (existing) throw new Error(`Refusing to create: entity ${id} already exists`);","typeGuard":null,"tryCatchPattern":"try {\n  await store.create('entities', entity);\n} catch (e) {\n  if (String(e.message).includes('already exists')) {\n    await store.update('entities', entity.id, entity);\n  } else throw e;\n}","preventionTips":["Always fetch-before-create when ids come from user input or imports.","Use generated unique ids (uuid/nanoid) rather than reusing natural keys.","Make seed/import scripts idempotent by checking existence before writing."],"tags":["storage","duplicate-key","filesystem"],"backgroundTag":"duplicate-entity-id","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}