mastra-ai/mastra · error · Error

Agent with id ${input.agent.id} already exists

Error message

Agent with id ${input.agent.id} already exists

What it means

create() first hydrates the agent from the source provider, then checks the memory store for an existing agent with the same id. If one is already present, it throws this error rather than silently overwriting. Agent IDs are unique keys in the storage layer.

Source

Thrown at packages/core/src/storage/domains/agents/source.ts:214

    for (const [versionId, version] of this.providerVersions.entries()) {
      if (version.agentId === agentId) {
        this.providerVersions.delete(versionId);
      }
    }
    await this.memory.delete(agentId);
    await this.hydrateAgent(agentId);
  }

  async getById(id: string): Promise<StorageAgentType | null> {
    await this.hydrateAgent(id);
    return this.memory.getById(id);
  }

  async create(input: { agent: StorageCreateAgentInput }): Promise<StorageAgentType> {
    await this.hydrateAgent(input.agent.id);
    const existing = await this.memory.getById(input.agent.id);
    if (existing) {
      throw new Error(`Agent with id ${input.agent.id} already exists`);
    }

    await this.persistSnapshot(input.agent.id, { ...input.agent }, 'Initial version');
    const created = await this.memory.create(input);
    this.knownAgentIds.add(input.agent.id);
    return created;
  }

  async update(input: StorageUpdateAgentInput): Promise<StorageAgentType> {
    await this.hydrateAgent(input.id);
    return this.memory.update(input);
  }

  async delete(id: string): Promise<void> {
    this.knownAgentIds.delete(id);
    this.hydratedAgents.delete(id);
    this.loadedHistory.delete(id);
    for (const versionId of this.providerVersions.keys()) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a different unique agent id
2. Check existence first with getById and update instead of create
3. Delete the existing agent if the re-create is intentional
4. Make bootstrap scripts idempotent (upsert semantics or skip-if-exists)

Example fix

// before
await storage.agents.create({ agent: { id: 'my-agent', ... } })
// after
const existing = await storage.agents.getById({ id: 'my-agent' });
if (!existing) await storage.agents.create({ agent: { id: 'my-agent', ... } });

const existing = await memory.getById(agent.id);
if (existing) return existing; // or update instead of create

null

try {
  await storage.agents.create({ agent });
} catch (e) {
  if (e.message === `Agent with id ${agent.id} already exists`) {
    await storage.agents.update?.({ agent }); // upsert fallback
    return;
  }
  throw e;
}

When it happens

Trigger: Calling storage.agents.create({ agent }) (directly or via the `created` hook path) with an agent.id that already exists in memory storage after hydration.

Common situations: Re-running a seed/bootstrap script without idempotency, re-importing agents from a source that already contains the id, retrying a failed create that partially succeeded, or a race between two writers creating the same id.

Related errors

• Version with id ${input.id} already exists
• Version number ${input.versionNumber} already exists for age
• EXPERIMENT_ID_CONFLICT
• Source provider ${this.provider.displayName} cannot read fil
• Source provider ${this.provider.displayName} cannot write fi

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/cc02bd136bb87a93. Report an issue: GitHub.