{"record":{"id":"4046130205ff9e2d","repo":"mastra-ai/mastra","slug":"this-name-version-number-input-versionnumber","errorCode":null,"errorMessage":"${this.name}: version number ${input.versionNumber} already exists for entity ${parentId}","messagePattern":"(.+?): version number (.+?) already exists for entity (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/filesystem-versioned.ts","lineNumber":612,"sourceCode":"    };\n  }\n\n  // ==========================================================================\n  // Version Methods (in-memory + git history)\n  // ==========================================================================\n\n  async createVersion(input: TVersion): Promise<TVersion> {\n    await this.ensureGitHistory();\n    if (this.versions.has(input.id)) {\n      throw new Error(`${this.name}: version with id ${input.id} already exists`);\n    }\n\n    const parentId = (input as Record<string, unknown>)[this.parentIdField] as string;\n\n    // Check for duplicate (parentId, versionNumber) pair\n    for (const v of this.versions.values()) {\n      if ((v as Record<string, unknown>)[this.parentIdField] === parentId && v.versionNumber === input.versionNumber) {\n        throw new Error(`${this.name}: version number ${input.versionNumber} already exists for entity ${parentId}`);\n      }\n    }\n\n    const version: TVersion = {\n      ...input,\n      createdAt: new Date(),\n    } as TVersion;\n\n    this.versions.set(input.id, structuredClone(version));\n    return structuredClone(version);\n  }\n\n  async getVersion(id: string): Promise<TVersion | null> {\n    await this.ensureGitHistory();\n    return this.versions.has(id) ? structuredClone(this.versions.get(id)!) : null;\n  }\n\n  async getVersionByNumber(entityId: string, versionNumber: number): Promise<TVersion | null> {","sourceCodeStart":594,"sourceCodeEnd":630,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/filesystem-versioned.ts#L594-L630","documentation":"createVersion scans all stored versions and rejects a new version whose (parentId, versionNumber) pair matches an existing one. Even with unique ids, version numbers must be unique per entity so history ordering stays deterministic.","triggerScenarios":"Creating two versions with the same versionNumber for the same parent entity; concurrent writers both assigning versionNumber N to the same entity; an import replaying versions of an entity.","commonSituations":"Manual version increments that didn't account for the latest stored version; optimistic client computing next versionNumber from stale data; parallel CI jobs writing to the same entity.","solutions":["Query listVersions for the entity and compute nextVersionNumber = max(existing) + 1 before creating.","Serialize writes per entity (lock/queue) if multiple processes can create versions concurrently.","Catch the error, re-read current max version number, and retry with the incremented value."],"exampleFix":"// before\nawait store.createVersion({ id: vId, [parentIdField]: entityId, versionNumber: 3 });\n// after\nconst { versions } = await store.listVersions({ [parentIdField]: entityId });\nconst next = Math.max(0, ...versions.map(v => v.versionNumber)) + 1;\nawait store.createVersion({ id: vId, [parentIdField]: entityId, versionNumber: next });","handlingStrategy":"validation","validationCode":"const { versions } = await store.listVersions({ [parentIdField]: entityId });\nconst next = Math.max(0, ...versions.map(v => v.versionNumber)) + 1;\nif (newVersionNumber !== next) throw new Error(`Expected versionNumber ${next}`);","typeGuard":null,"tryCatchPattern":"try {\n  await store.createVersion(version);\n} catch (e) {\n  if (String(e.message).includes('already exists for entity')) {\n    // recompute next version number and retry once\n  } else throw e;\n}","preventionTips":["Always derive the next versionNumber from listVersions output, never from client state.","Serialize version creation per entity in concurrent environments.","Retry with recomputed version number on conflict."],"tags":["storage","versioning","conflict"],"backgroundTag":"duplicate-version-number","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}